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VIEWPOINT 


By llene Hoffman 


User Solutions to Pesky Trash Problems 

How would you react if you tossed a bag of trash in 
the dumpster only to have it bounce back to your feet? 
Odd as tliis sounds, the inability to empty the Trash has 
been one of the more unexpected errors encountered all 
too frequently in Mac OS X, Web pages are filled with 
shareware solutions and instructions on how to drop into 
the command line interface to solve trash problems, but 
assuming you bought your Mac because you like the 
graphic user interface, lei's look at some common 
problems and solutions to solving those annoying "can 1 ! 
empty the trash" messages. 

First, let me caution you, the Trash Can should not he 
used to save files for later use. The Trash's function is to 
remove files from your drive. In fact, files aren't really 
deleted, but the pointers to the file (sort of like location 
coordinates) are removed, so thaL the hard drive space is 
made available for another file. Tliis is why you can 
recover deleted files. That aside, when you pul something 
in the Trash, you should delete it before shutting your 
computer down. Each user in Mac OS X has a separate 
Trash folder inside the Home folder. This folder is 
invisible to the user, but you can see files you pul in the 
Trash until it is emptied. 

If you are not sure yon want to toss something, make 
a new folder inside your documents folder and call it 
Undecided, so that you can save ii for later. You can drag 
the folder to the Dock, which puts an alias in your Dock 
for easy access. 

To avoid I he "Are you sure you want to remove the 
items in the Trash permanently" dialog, you can press 
Control and click on the Trash. Select this menu item to 
empty the Trash without the dialog. You can also press 
sh ift-opt ion-command and the delete key to quickly 
remove a file. Some common errors and solutions are 
below. 

Problem: Error Message: 

"The operation cannot be completed because you do 
not have sufficient privileges for 501" or "The operation 
cannot be completed because you do not have sufficient 
privileges for some of the items.® 


Explanation: 

501 is the numeric equivalent of the first user set up 
in Mac OS X; this means you in most cases. 

Privileges refers to who owns Lite file, who can write 
to it and who can read it, and therefore, who has the 
correct permissions to throw the file out. 

Possible Causes and Solutions: 

1. This may be caused bv one of programs you've run 
incorrectly setting or altering the permissions on one or 
more of your files. An interruption in power, or an 
application freeze can also affect privileges. 

You can check and/ or change the permissions of the 
file. Click on the file once and choose Show Info from the 
File menu (or press Command and 1 together). In the pop¬ 
up menu, in the Info window, choose Privileges and 
check the file's permissions. You need Read & Write 
permissions to delete a file. If a folder is the problem, 
remember to apply the changes to enclosed folders also. 
If you can't change the file's privileges, you can use 
Apple's Repair Privileges I'liiity to restore Apple-installed 
programs to their default permissions, if you are using 
Mac OS X 10.1,5. (You can find the Repair Privileges 
Utility at: 

( h ttp://d< kis . i n fo .apple.com a rt tele - ht ml ?a rt nu m = 1 06900. ) 

If these solutions don't work, you can also start up 
from Mac OS 9, use Sherlock to find the file and delete it. 
You cannot delete a file from OS 9 while in Classic Mode 
though. 

2. Attempting to throw away a locked file can also 
generate the insufficient privileges message. 

Again, choose Show Info from the File menu. Undick 
the Locked check box and move the file into the Trash 
again to delete ii. Prior to Mac OS X 10.1.5, if a file was 
locked while in Mac OS 9, von would have to restart in OS 
9 to unlock the file before you could toss it. This seems to 
have been fixed in 10.1.5. 


llene Huffman is the Community Director and Editor of MacHxlt Forums and a Contributing Editor for MacTeeh magazine. She stole her first 
Mac from her Dad in 198^ after asking him to buy a PC, She's not touched a PC since! She is also the mother of a budding jazz musician and 
two capricious clogs. 
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Problem Error Message: 

Can't empty the trash becasue ".trash items arc in 
use." 


Explanation: 

Your computer thinks that a file is still open, and 
therefore cannot delete the file. Some of these problems 
may be fixed by upgrading to Mac OS X 10,1.5 or Mac OS 
X 10*2. 


Possible Causes and Solutions: 

1* Check to make sure that the file is dosed. Switch 
to the application used to create the file (click on the icon 
in the Dock), If you’re not sure, quit the application used 
to create the file, then Empty the Trash. 

2, If you are in the Columns View and the file is 
"open 11 in the Preview screen, the system is using the file. 
Put the file away by (i.e. take it out of the trashX Close 
the Preview screen in the Column View and drag the file 
to the trash again. 

3. Some users have reported that waiting a while, and 
even tossing out another file and then emptying the Trash 
resolves this problem also. 

If you want to resolve your trash problems by using 
other software, you can look at programs such as: 

Batch mod which changes file permissions and can 
empty the Trash, or 

Trash It! which is an AppleScript for emptying the 
Trash, or 

ToTheTrash which helps you manage your about to 
be trashed files* 

You can search Version Tracker 
(www.vcrsiontracker.com) for other current Mac OS X 
utilities. You really shouldn't have to resort lo using 
Terminal to empty your Trash, 

Now, if you like typing, there are also solutions to 
fixing your Trash problems from the command line 
interface, fn our next article we'll explore some of the 
those options for the geek in all of us. 
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- transfer files: FTP TFTP 
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- encode/decode: MIME, NetCode 

- access directories: LDAP 
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- build packet applications: UDPPort. Multicast 

- remote access: Telnet, Rexec, Rshell, RCP 
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today from www.nsoftware.com! 
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MAC OS X 


By Andrew C. Stone 


When Wild Animals Bite 


Or How To Workaround Cocoa bugs 


Of the last 50 articles l have written about Cocoa and Mac 
05 X, I think 49 have extolled the virtues of object oriented 
programming and the unparalleled advantages of using the 
dynamic runtime of Objective C. You might think I d been led 
some KoolARl, and you might not be too far off But effects and 
mileage will vary, 

The question that might arise in your mind is “Aren't there 
any serious drawbacks lo using such a high level .system?". And 
the answer to that would Ik 1 the same as the drawbacks to any 
complex system: “Yes - Beware of Bit Rot", the inevitable 
complexificalion of simple architectures over time as more 
people work on it. 

Once upon a time, the entire Cocoa development system 
was in the hands of a few able engineers, which kept it focused 
and robust to tween system releases. However, with Mac 10.2, 
aka Jaguar, we've seen a new and dangerous trend. 
Components that have been working almost flawlessly for over 
len years have been “re-plumbed" without enough real world 
testing, and this can cause trouble for applications which push 
the envelope. Sometimes the pressure to release a new version 
Ls greater than the ability to do adequate quality control, so all 
of this is quite forgivable. 

The same features that seem like an advantage can turn into 
a disadvantage! Since a Cocoa application links against the 
runtime AppKit and Foundation frameworks, when 
improvements are made to a subsystem framework, your 
application, even unreeompiled, will take advantage of these 
improvements. For example, Mac 05 X 10,2's text system 
introduced 3 new tab types: decimal, right aligned, and centered 
tabs. Users of our page layout and web authoring program, 
Create®, now automatically have access to these features under 
10.2 - even with versions compiled under 10,1, By the same 
token, some changes in the subsystem framework can break 
existing, unrecompiled applications. 

Because of the relatively small number of Cocoa engineers 
at Apple compared to the number of traditional Carton 


engineers, there has been an increasing Lendentiv to “pollute our 
Cocoa purity with underlying Carbon implementations, and 
consequently, unexpected results cun ensue! In Object Oriented 
theory, all objects are so well encapsulated and isolated that one 
can just swap out implementations of components and 
everything should just work. Reality just doesn't conform to these 
simplistic expectations. 

When Carbon Mft Cocoa 

In the lust several years of shipping and maintaining OS X 
applications. I've found that most of the problems have come up 
where traditional Mac OS 9 technologies have tocn shoehorned 
into the Cocoa model. The interstice between them is riddled 
with the same ambiguities that bedevils any organization that is 
a hybrid of philosophies and techniques. Cocoa's AppleScript 
implementation is an example of this from the outside, it looks 
neat and dean, but getting it to work just right is a lot tougher 
than normal Cocoa programming tasks. 

One object whose plumbing was changed in 10.2 is the 
NSFrintlnfo - an object which maintains information about page 
size, orientation, margins and selected printer. The backend Print 
Manager grew out of the Carbon Tioga effort and is coded in C 
and (>+. In 10.1, you could set the page size to any value (ideal 
for custom page sizes) with the simple invocation: 

ImyF rim Info sstPapo rSizeiMSMakeSizetHometWidthlnPoints , 
sonteHeifthtlriFointsJ]; 

And rlie priiulnfo dutifully obeyed. This is useful for 
designing large scale posters to be printed offsite or for web sites 
with long content. However, in Jaguar, new behavior was 
introduced which attempts to see if that size is “valid 11 for the 
given printer. To be fair to the Apple engineers, I can see how 
this might be useful. But from my jroint of view, it broke the 
existing version of Create®! Luckily, since our corporate 
philosophy is free upgrades downloadable via the Internet, some 
quick coding, testing and uploading would solve the problem. 

This new- validation behavior occurs whenever 
'setPaperSizef is called, and in rhe ease of Create®, that's when 
the document is unarchived from a file. So, when you open an 


Andrew Stone, founder of Stone Design <www.stone.com>, spends too much lime coding and not enough time gardening 
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old Create document with a custom size, the old size is lost 
forever, and all of a sudden, size *A4* is chosen! What's worse 
is that any attempt to even read this paper size, such as with the 
public NSPrintlnfo API call -(NSSize)paperSize or even ■ 
objeetForKey on the dictionary returned from 
(NSMutableDioionaryklictionary will also trigger this new 
validation l )clia v i or. 


Redemption Song 

So, what's the workaround? Somehow, well find Cocoa's 
redemption! For any flaw that comes in a shipping OS, there 
are ALWAYS tricky ways in Cocoa to do post-ship fixes! Once 
again. Objective C Categories save us from getting egg on our 
digital faces. 

By examining the header file NSPrintlnfoJi, we see a private 
instance variable (TVAR), _attributes, which is the actual mutable 
dictionary which holds all the values of the Printlnfo: 

©interface NSPrintlnfo ; NSObjectOtSCopyfng. N$Coding> I 
©private 

NSMutableDicticmary 4 attributes; 
void ‘jnoreVsrs; 

1 

Because the IVAR is designated private, even a subclass 
cannot access ii directly, so subclassing NSPrintlnfo won’t work. 
Only a category of the class containing the private IVAR can 
directly access the variable, Here’s a category that can return any 
set value for paperSize, without triggering the unwanted 
validation be ha v ion 

©interface NSPrintlnfo (peek) 

(NSSiKcigrabOriginatSize: 

©end 

©implamentation NSPrintTnfo{ppoR) 

- (NSSIze) j^rabOrigins 1 Size I 

id ofaj = L^ttrlbutes objeetForKeyiNSPrintFaperSizel: 
return ohj? [obj elaeValue]; NSZeroSize: 
t 

©end 

Documents which had no custom page size wall return 
MSZeroSize, which indicates that no extra work will lx* required. 
So* here's how well use the new category method: 

NSPrintlnfo "printlnfo = [NSUnarchiver 
unarchiveObjeetWithData:obj]: 

H a freshly unarchived Printlnfo still has its old values in the dictionary..,, 
if (printlnfo) I 

NSSiztt taw - Iprlntlnfo grabOriginalSizej: 
if (t.NSRquaJSizes (raw, NSZeroSiZfc)) \ 

// it could have been written 
// by a 10.1 version of Create* 

[self setUpPrint hifo ;priuriiifu LuP&perSi7.e:rnv]; 

1 

[self set PrintInfo:p ri ntl n fo}; 

1 


Now, all we need to do is fake NSPrintlnfo out so that it 
thinks the custom paper size is valid. To do this, 1 had to dig 
into undocumented API using class-dump as explained in 


several of my last few articles* and even more dreaded by an 
Objective C coder, into the Carbon header files! It turns out 
that there is a C function to make custom paper sizes 
programmatically, which stands to reason because the new 
Page Setup.., panel in Jaguar has a popup option to set custom 
paper sizes: 

OSEtarus PMFapcrCreate(FMPrinter primer* CFStringRef id, 
CFStringRef name, double Width, double height, const 
PMPiiperMargins ‘margins, PMPaper *paperP); 

And well call it like this: 

GSStatus osStatLis “ FMPaperCreatfd [[pi printer] 
_printer] . (CFStringRef)[NSStrlng 

stringWithFortnat:©“"XId"„no!f]. (CFStringRef) (NSString 
EtringWithFonnar :©"%2.,7f X % 2 * 2f",userW.useclij , (double) 
paperSize.width*(double) paperSize,height. marginPtr, 

RmyPaper); 

If PMPaperCreateO returns an OSStatus of 0, then a new 
PM Paper * object (which you'll need to later release after use) 
has ix:en created in my Pa pet The first parameter* PM Printer, can 
lx* returned from the NSPrintlnfo via undocumented NSPrintlnfo 
API, -(PMPrimer)_printen 

Ifpi printer] ^printer] 

Another sweet feature of Cocoa is “toll-free bridging” 
between Core Foundation objects, such as a CFStringRef and the 
equivalent Cocoa object, in this case, ihe NSString. We will cast 
the NSStrlng parameters to CFStringRefs just to hush the 
compiler. The other fancy dancing that we Ye doing is using the 
pointer to memory of the document object as our unlquing 
strategy for the second argument, but it could be any string ax 
long ax it is a unique Identifier: 

(CFStringRef) [NSString ntringWithFotmat:©"Sid**.self) 

Finally, we ll name the custom page in the user’s units by 
converting the points to their measurement units - these 
functions are included below. 

// these function* m declared here: 

#i import (GoreServices/CoreEervices,h> 

#import (ApplicatlonServices/ApplicationServices.lO 

Lypedef struct OpsfjueFMFaper ‘PMPaper; 
typedef struct [ 
double top: 
double left: 
double bottom; 
double right; 

\ PMPaperMargins; 


OSStatus PWPaperCteate(PMPrinter printer, CFStringRef id, 
CFStringRef name, double width* double height, const 
PHFaperkargins ‘margins, PMPaper "paperP); 

- {voidtsotlJpPrintlnlo: (NSPrintlnfo *)pi 
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toPaperSisie: (NSSi2e)pap6fSizc [ 

if (flout (NSAppIQtVersimiHuraber) <- 
NSAppKitVersionNuaberlO_n f 
r Qua 10.1 -10. U system*/ 

// nothing special to tki... 

I else t 

/* 10.2 or later system 7 

float; tmerW " eotiverrToOserTJnii:s(paperSize.width); 
float userli ~ co nv eU Tot! ser Units(poperSizc.height); 
PMPapotHarglns mat gins; 

PHPaperHargins ^arginPtr - ^margins; 

// dixs C suck or wlut' 

PMPaper # rayPaper; 

// Create uses WYSIWYG full page model: 

margins. top = margins, left: c margins .bottom - 
margins.right ® 0.0; 

USStatus osStatus “ PfciPaperCreate([[pi printer] 
_prinierj , (CFStringRef)[NSString 
stringWithFonnat:@”%id M T self]* (CFStringRef][KSString 
stringWithFormat \$*Xl ,2f X %2.2f" P liSerW.userH] .(double) 
paperSize.width,(double) paperSize.height. marginptr, 
&myPaper); 

if (osStatus 1- 0) I 

//You may want to tki something else Herr 

NSLog(y"Trouble creating a custom page size: %f by 
Xf" .paperSize,width, pape rSize.height t : 

I 

I 

// on t(l I this just works: 

[pi setPaperSize:paperSizel; 

) 


// getting user units from an NSLtecrDdault; sometimes C is cool! 

float 

pointsFroraUserUnits() 

( 

switehf [[NSlIfierDefaultn standardllserDefaults] 
iniegeirForKey;@"Meani3rementtlnitFr rt l) I 
case 0: return 72.0; 
case 1; return 28.3 !j; 
case 2: return 1.0; 
case 3; return 12.0: 
default: return 72.0: 

1 

I 

float 

converiTollserUnits(float points) 

I 

return points / pointsFrotnUsedlnitsO ; 

I 


Conclusion 

So now t our printlnfo will return the correc t new size! Well, 
i he dual hasn't settled entirely, so hopefully this will work ant) 
continue to work in the future. Ideally,, NSPrintlnfo would just 
<J do the right thing" in terms of creating these custom page sizes. 
The proposed solution doesn't address custom page size 
uniquing and coalescing of similar-sized pages - but then, 1 
haven't finished coding the solution entirely either! Even the 
mighty Cocoa has its compatibility weaknesses as it grows, but 
its native power can even pull the tractor out of the mud when 
it gets really stuck. 
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CARBON 

DEVELOPMENT 


By Ed Voas, Apple Computer, Inc. 


HIObject:The Carbon Object Model 


Learn about the new Toolbox object 
model introduced in Mac OS X 10.2 


Introduction 

Apple's Human interface Toolbox (HlToolbox) has always 
been object-oriented There were various objects, such as 
windows, controls, menus, etc, and those objects could be 
manipulated by APIs meant to deal with them (Show 1 Window, 
ct. al). But there was no really good way to override standard 
controls or even derive a new custom control from another 
control, UlObject is a new mechanism that allows you to 
subclass and override standard toolbox objects as well as treat 
those objects in a polymorphic way. This article explains all 
you need to know about this new world, and serves as a 
Foundation for learning about the other HlToolbox 
technologies that are in Jaguar 

What Is HIObject? 

HlObject is Apple's new common object base class in Jaguar 
Tor the HlToolbox. It is the foundation for everything Apple does 
these days in Carbon — it is something that all Carbon 
developers should learn about and understand, 

People long assumed Apple had a C++ hierarchy under 
the hood for things like controls, but in reality they never did. 
The move to HlObject was something that came out of the 
move to a real C++ framework internally for basic object types. 
Under the skin, the Jaguar Toolbox is a wildly different beast 
ihan in previous releases. Most of this change comes from 
Apple’s re-arch heeling to use HlObject and HI View (the new 
view system in Jaguar), 

Essentially, an HlObject is any type of object that can send 
and receive Carbon Events — windows, menus, controls, etc. — 
basically all the objects that had an event target anyway. 
HlObject is an object model where an HlObject is the object- 
oriented encapsulation of an event target, and the methods* you 
call to manipulate this object are implemented as Carbon Events, 

To be exact, windows, views/controls, menus, the 
application object, toolbars, and toolbar items all derive from 
HlObject. Diagram 1 shows a portion of ihe current 


HlObject hierarchy. The purpose of doing this is to gain some 
form of polymorphic behavior when dealing with these 
objects. For example, if you obtain a reference to a 
WindowRef, you can safely call HlObject routines on it, such 

as HIObjectGetEventTarget. 



Diagram /: The HlObject Hierarchy 

Having Toolbox objects all derive from a single-base class 
might not seem important at first glance, but as you start to 
use HlObject more and more, you will realize that the 
Toolbox has just taken a huge step forward into an exciting 
new world. The more Apple improves the Toolbox, the faster 
they can make changes and add features. This change has 
done incredible amounts of good already — the addition of 
the Accessibility features in Jaguar required much less effort 
due to the new implementation. 

The new data type Apple has introduced to represent an 
HlObject is an HJ Object Ref. The new objects introduced in the 
Jaguar ToolLiox, such as toolbars, are merely Lypedefd to 
1 OObjectRef, Legacy types such as ControlRef are not rypedefd 
to maintain source code compatibility. For example, if Apple 
typedefd ControlRef and Window Ref both to HIObjectRef, and 
you had an overloaded C++ method that took a ControlRef in 
one variant and a WindowRef in another, your code would 
probably no longer compile since they equaled to the same type. 
Rather than wreak havoc, Apple decided to keep things the way 
they were. You can simply cast references to those types into 
HlObject Refs as needed. 


Ed Voas is the Manager/Teeh Lead of the Carbon High Level Toolbox, When not coding, he is usually out applying 5 coats of polish to his car. 
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The new HlObject.h header file contains a routine to create 
an HlObject, hut nothing to retain or release the object. Well 
then how are you supposed to use an object you could never 
destroy? Well, in reality Apple has done something cool — 
HTObjecix are actually Core Foundation types! That means you 
can add anything that is derived from HlObjeci (even a window) 
into a CF collection, such as a CFArnay, It also means you simply 
use CFRetain and CFRelease to retain/release the object. 
Wicked! But you do need to be careful about such things, as 
windows for example may not go away when you expect them 
to if you are retaining them in places. You can also cause circular 
retention (which sounds very painful), so be careful. 

Polymorphic Functions 

Lets first check out the routines you can call on any 
HlObject There aren't that many at present. That’s a gotxl thing, 
as it makes it easier to learn. 

Event Handling 

To get the event target of any HlObject, you merely call 
HIObjectGetEvGntTarget. This is very nice! It means you can now 
keep an array of dissimilar objects such as controls and 
windows, and just iterate the list, getting their event targets, For 
example, you can use this technique to keep a list of objects that 
are interested in receiving particular notifications. It doesn't 
matter if ifs a window, control, or toolbar item. All you rare 
about is that they accept carbon events. There is no need to 
track what type of object they are and call the appropriate API 
to get the taiget. 

Class Identity 

An HlObject class is uniquely identified by its class ID, 
which is a CFString. Apple uses java-style namespaeing for its 
classes (com.apple.blah). To obtain the class 11) of an object, you 
call HIObjectGopyClassID. This returns a copy of the class ID 
siring for you to inspect. You can compare ii to other class IDs 
to see if an object is of a particular type, for example. Be warned 
that if a class ID is not documented in any header (and at 
present only two of them are), you should ntn rely on those 
class IDs remaining constant between releases of Mac OS. 

It’s also useful to find out if an object you have is something 
of a specific type — typically referred to as an ‘is-a 1 rest. For 
example, if you have a push button's Control Ref in hand, you 
can see if it’s a control by asking if It Is derived From 111 View: 

if ( RlObjeetlsQfCiass( anObjeet. kHTVlevniassTn ) ) 

I 

// It s an HIVkwt 
I 

else 

I 

abort0; 

1 


CrcatcPushRuUvnCctttroK window, ♦*, ^control ): 

// do some fun stuff htrt, maybe add it to an array, 

// which will retain ii. Removing it from die array 
// would decrease the retain count as expected. You 
// must use the standard CF type callbacks when you 
// create Lhe Array though. 

CFRelease( control ); 

CFRelease is now a synonym for DisposeControl, 
DisposeWindow, and DisposeMenu, New types (like the toolbar) 
have no specific retain or release calls of their own. 

Debugging 

In the Toolbox, there are several functions you can call to 
print debugging info for an object to stdout. Some of them aren't 
exported, so you can only call them from gdb. And the names 
are not consistent — even engineers at Apple can seldom 
remember what they are. This was fixed in HlObject by 
introducing one base class function to display die debugging 
information for an object — HI Object Print Debug Info. Call it with a 
window or control reference and you wall see all the types of 
information it prints to stdout. 

And much much more! 

Well, not really. There are a couple of routines to deal with 
Accessibility, another major feature in Jaguar, Accessibility is well 
outside the scope of this article though, and deserves an entire 
article of its own. 

There are also a couple of other APIs you should know. 
These are important primarily when creating objects of your own 
design. Thai s precisely what we ll cover next, so we’ll talk about 
them as we go. 

Creating Your Own Objects 

You can create HlObjeci classes of your own and even 
subclass ones provided by the Tcxillxix. You would most likely 
do this to create a custom view or toolbar item. Or you might 
create a custom HlObjeci so you can have your own event target 
to pass to Toolbox APIs, 

Let's get right into how to subclass something. We will 
create a simple subclass of 111Object, lhe first thing that we need 
to do is register our new subclass with the HlObject system. You 
do this via a call to HIObjectRegisterSubclass: 

extern OSStatUs 
K T Ob j ec L Re gi s t e rSu b c 1 a s s ( 

CFStringRef 
CFStriagRef 

QptionBits 
EventRandlerUPP 
Dlnt32 

const EventTypeSpcc * 
void 1 

TtTObjcciClassRef * 


inClassID, 
inBaseClaesID, 
inOptionfi. 
inConstructProc* 
InNumEvcnts, 
inKventList. 
inConstructData, 
outclassRef )3 


Believe it or not, we’re running out of polymorphic functions! 
As I mentioned before, you can use CF routines to retain or 
release an HlObject. So the following is perfectly legal now: 


For our purposes, we would call this function as follows: 

const EventTypeSpet kMyFunObjectEvents = 

I | WEventClassffTObject, kUiObjectConstruct I, 

( kEveritClassJllObject, kHlObjectDestruct I 

1 ; 
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^define kMyFunObjeciTO \ 

CFSTRt “eotrutstycumpany. funobjeet" ) 

Hi0bjectRegisterSubcl35$ t 
kMyFunObjectID* 

MULL. // no base daw* 

0, // no options 

KyClassHandlsr* 

GerKvonrTypeCount( kMyFunObjoctEvonfs ). 
kMy FuuOb j ect&vonts, 

0. // no handler daft 

StclassRef 3; 


// an error (Tf you ever wondered why sometimes the Toolbox 
// returns mcmFuUErr on a system where you can never run 
H out of memory Without ihe system dying a horrible death. 

H now you know’) We are reusing the object variable above 
ff since it’s not used for anything in this particular example 
ff during curtstruaiutt 

object “ flu?lloc( slzeoft MyFunObject ) j; 
ret] til reaction £ object. Cant A1 locOb ject, 
result = memFullKrr ); 

object-)ref = ref, 

object'>isPutiEnabled * false: 


By passing NULL for the tnBaseClass parameter, we are 
telling the function that we want to be a subclass of HlObject 
itself. This function sets up MyClassHandler as a handler that will 
automatically get pushed onto an instance of this class when one 
is created. In this example, this handler only deals with two 
events — construct, and destrucL These two events are, in fact, 
required for any subclass you are registering. If you try to 
register a class handler that does not respond to these events, 
ihe earth will open up and swallow you. Either ihai* nr an error 
will be returned. 

figure l shows our class handler for our custom object. 


Listing 1: Class event handler 

fi simpler tibject 

struct MyFunObject I 
HlObjectRef reT; 

Boolean isFunEnabled; 

Is 


OSStatus MyClassHandler( 

EventHandlerCallRef inCallRef, 
EverstRef iuEvent, 

void • intfserOata ) 


OSStatUE result = eveniNotlJaudledErr; 

UInt32 theClass. theKind; 

MyFunObject" object = (MyFunObject MitiUserData: 


// Please note that object above is overioaded in this handler, 
if for the k Event Hi Objcctft mstmci event ONLY, the inllscrOaft 
ff parameter is the tisrr ibtu you passed (o HlfflvjectRcgistcrSuIx’bss 
ff For all other calls to this function. it is the object pointcr that you create 
ff and return in your handling of tire kbwntHlObjcctConsiruct as scctl below, 

theCiass = CetEventCiass( inEvent ): 
theKind • GetEvenrKind £ inEvent J; 


switch ( theClaas ) 

l 

cane kEventClsssHTObject; 
switch £ theKind ) 
f 

case kEventHJObjectConstruct; 

I 

HIObjectRef ref: 

//When the construct event Is called, you are handed the 
if INOhjcctRef that is being constructed In this example, 
fi we save it off in our object,This is wliat you generally 
// want to do so you can call appropriate Toolbox APIs 
fi as needed, since your object pointer (created below), 
ff is nut a real JllOhjctt. 

result ■ GetEventPararaeterf inEvent* 

kEventParamfnQbjectTnntance, 
typeHIObjectRef* 

MULL, 

sizeof( HIObjectRef ), 

NULL, 
iref ): 

require_noerr£ result. ParameterMissing 3: 

ff Create the bin object here. If we fail to mailtx it, return 


// OK. Here’s the key: we replace the instance parameter 
ff with our object pointer The type of the parameter MUST 
// be TypeVniilPrr It 's the law,The Toolbox will store this 
ff off with the HlObject .This will allow you to call 
if I ilObJect LiynamicOst laler tl'you need to to get your 
// object pointer back front an UiOhjcuRcf. 

SetEventParamptnr( tnEvent* 

kEvent Pa ramMTObj ectTAstance* 
lypeVoidPl r, 
slzeoff void " 3- 
^object ): 

1 

break: 

case kEvent H T Oh j ect Des t rue t: 

//This is easy, Just dispose of the object Do NOT call through 
ff with Call Next Event Handler —Very Bad Things will happen. 
//This is a top down destruction. Don't try to gt‘t fancy! 

free( object J: 

break: 

I 

break; 

\ 

CantAllocObject: 

Fa rameterMissing: 

return result; 

I 


How an HlObject is constructed 

In order to truly understand what is going on in the class 
handler, let’s discuss the steps the Toolbox takes when creating 
an HlObject. 

The Toolbox sends construction events Ixjttom-up, as you 
would expea in C++ or similar runtime models. This means that 
base classes are constructed before Nulxlasses. 

[Test, the Tool)x>x creates the base 1 HOhject. This is where 
the actual HTObjectRef value is created. H Is important to note 
that unlike C++ (where the subclass’ (his pointer is the same 
value as the base class 1 this pointer), a subclass* object pointer is 
not technically an HlObject. Jt is merely data stored with ihe 
HlObject for the specific class. Well see how this works later. 
After the base HlObject is created, all other subclasses of 
HlObject between it and your class are constructed. This means 
that if you are creating a object of lype Fcx) s which derives from 
Bar, which derives from HlObject, first the HlObjea is created, 
then Bar, and finally comes your 15 minutes of stardom. 

Once the Toolbox creates your immediate superclass* it starts 
the process of constructing your part of this aggregate HlObjea. 
First, it takes the event handler you registered and installs it onto 
the event target that was created for the HlObject. As mentioned, 
this handler must be registered for the kEventHIObjectConstrud and 
kEventHIObjectDestmd events. 
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Next, the Toolbox directly calls your handler with a 
kEventHIQbjectConstrucI event, When called directly, you are not 
being called in the context of a handler Mack, so you cannot call 
CallNextEveniHandler, unless you like to crash. The inUserDala 
parameter of your class handler is passed the value you specified 
for the inConstructData parameter when you registered the class, 
Typically, during construction you will allocate memory for your 
own instance daLa, This allocation might he as simple as calling 
maUoc or NewPtr, or it might involve treating your own C++ 
object, in the construct event, you are passed the base 1 HlObjectKef 
of the object being created. You should store this IflObjectRef in 
your own instance data for later use. Ymi should then use 
SetEventParamster to set the kEventParamHIQbjectlnstance 
parameter in the const met ion event with your instance data. You 
must use typeVoidPlr as the type. 

Once back from sending the event, the Toolbox looks for 
your instance of type Void Ptf in the event and stores it with the 
object. It also sets the user data parameter of the event handler 
it installed to lie this instance data. Following the construct 
event, all calls to your event handler will have the instance data 
you returned to the Toolbox, At this point, all events are now 
sent to your object using standard Carbon Event mechanisms. It 
is only the construct event that is special. 

Once construction has completed successfully, the Ttxillxix 
will send your object a kEvent HI Object! n totalize event. The 
initialization stage is optional; i.e. an object does not need to 
respond to the initialize event unless it is expecting certain 
parameters to be passed In it nt creation time. This is where those 
parameters may be fetched. We 11 show an example of this shortly. 
The first thing you should do is call through to tlie ‘Inherited' 
method with CailNextEventHandler. Once back from that, you 
should verify the result code returned is noErr, indicating that the 
base class initialize!! properly. If it did, you should extract any 
initialization parameters and do whatever your object requires in 
order to properly initialize. If the base class did not initialize 
properly, you should return the error that CailNextEventHandler 
returned as the result of your handler immediately, doing no 
work. The Toollxjx will see the error code and proceed to destroy 
the object (see Object Destruction/ Ixduw), Your object must lie 
able to lx- destroyed in a partially initialized slate such as this. 

Upon successful initialization, the HlObjectKef is returned 
to the caller of I UObjectCreate. From there, you can have all 
sorts of cool fun. 

Object Destruction 

Destruction is top down, as in C++, When an object's retain 
count reaches zero, the object is destroyed. During destruction, 
the Toolbox sends a kEventHIObjectDestrucl event to the object, 
litis event will just propagate using the normal rules of event 
handlers (top-down), which is exactly what we want, ft is a very 
bad thing to call CailNextEventHandler during destruction. Just 
clean up and return from your handler. 

Creating an instance of your class 

To create an instance of this new object class, all we need 
to do is make this call: 


HIObjectRftf obj: 

err ** HIGbjectCrcatef 
kMyFunObjectTF'. 

HULL * // no initialize cvcnl 
&obj ); 

At this point, you have a nice abject of your own design. 
But it doesn't do much, does it? You can create it and release it. 
Let’s add an API to set the fun enabled boolean. See listing 2 
for the code. 

Listing 2: Adding APIs to your class 

OSS talus HvFunOb j ectSetFutiEnabled ( 
tllObjectRet inObject. 

Boolean inEnabled } 

I 

MyFunQbject* obj; 

OSStatus err * noErr; 

// Cast the HlObjmRrf tended |o us to uur inimul tnMarxv dim 
//What this does is look up the Uuui we returned in the 
ft kUveutPjntmlJIOiife^lnsLifiee parameter when wc tefidfcd the 
// kiivcruHlObi«.tCx)n!i[met event in listing Lit this fiinelion 
// ttiums NULL, then the object is not nf the class specified in 
// the second parameter. 

obj ™ (MyFunObject* jHtObjectDynaaiicCast ( 
inObject, kMyFunObjectID ): 

require_aetion( obj. InvaliriObjoct, 

£rr - kHyTtivalidClaEsIB ); 

// OK. We have our obfett now Store ihe value 

obj MsFunEnabled * inEnabled: 

1nvaiidObject: 

return err; 

I 

This is pretty straightforward, but there is one oddity — the 
dynamic cast call. Its necessary lxrcau.se the API we wrote takes 
an HI Object Ref and not a MyFunObject jxnnter, This starts 
getting into the ugly truth of it all — your objects are not really 
\ 11 Objects! When it comes right down to in they are just some 
value that you wish to associate with an 1 HObjecl 

Diagram 1 shows a comparison between a C++ object 
layout and an lllObjcct layout In C++ the object is a unified 
bkx’k of memory, it can do this because* it’s part of the language 
runtime. With H (Objects, the objea reference always points to 
the 1U Object, and the data stored by subclasses are kept track of 
in the HlObject itself, 

Remember that when you handle the kEventHIObjeetConstruct 
event, you are given the HlObjectKef for your objea ahead of 
time. The object we created in listing 1 is just our blob of data 
that we want stored with the 1 ilObject for our class. We get that 
data back with HIObjectDynamicCast if we happen to liave an 
HIObjectRef in hand. 

[f you think about it though, this easting' mimieks C++ very 
well, in that you can't take a pointer to a base class in a class 
method without ‘casting up’ to your class before using it. So 
while the guts are different from C++, the mentality is noL The 
main difference is that we can't rake our strua pointer and treat 
it exactly like an HlObject, because, like, it's not. 
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One last thing to note is liiat while HiObject s data layout is 
somewhat disjoint, the Viable' layout is just as you'd expect. 
There is one unified Event Target that acts as the viable. Only 
the data is spread out. Also, there's nothing to say that in the 
future Apple couldn't come up with some superior scheme to try 
to make iL better There is an ‘options' parameter in the call to 
HIObjectRegisterSubclass, so it would l>e possible to define new 
types of subclasses if Apple so desired, 



Diagram /. C++ vs, IlJObfect Data Layout 


At this point, you know all the hard stuff. The rest is just 
academic. Let 1 * extend our object a bit. First, let's write a new 
API to create an object. It will wrap the call to MIObjectCreate. 
It will also take a parameter indicating die initial value of our 
Tun enabled' boolean. 


CreatePushButtonControl are implemented using this exact same 
formula. 

Now, in our class handier, w p e need to add a case to handle 
the initialize event. See listing 4 for how to do that. 

Listing 4r Adding the initialize Handler 


OSStatuit MyClassHandler ( 

RvfintHandlerCallRef inCaliRef, 

Evcntftef iiiBvcnt f 

void * InUserData ) 


OSStatus result - eventNotliandledErr ; 

HyFunObject* object ” (HyFunObject*)itiUsurltar.a; 


case kEventHlQbjectinitialise: 

// Be suit 1 m cat 1 our inherited' initinliw first. Then extraa 

if our parameter and bvr 

result = Cal 1NextEventHsndler{ inCallRcf, 
luEvcnt ): 

if { result ™ noErr ) 

t 

result - GetEVentPara ik? tor( inEvettt, 
kMyFuiiEna bled Pururn, 

TypeBoolean, NULL, 
oizeoff Boolean ). NULL. 
kobjeer >isFunEnabled ): 

I 

break: 


I 


listing 3: Our Creation API 

OSStatus WyFunObj e^tCreateI 
Boolean InFunKnabled. 

HlObjectSef" outObject ) 

EvcntRef event: 

OSSlatus err - noErr; 

ill Ob jectRef object; 

//To pass parameters m our object at creation lime, we need to use a 
// Carbon Lvcnt We create it here and add our Itoolead parameter. We 
// then pass ii into HIObjcrtCtote.This event will be sent to our 
// object at initialize time You must lake care to use die correct class 
// and ID tor this event. 

err = Createlvent( NULL, kEveiitClaasHTObject. 

kEvontHTOb jectlnitialize, GetCurrentEventTiiaeO . 

0, firevent ): 

rfiquire_n<?Krr( err* CantCreatelnitEvent J; 

ikitEventParanaater( event, kMyFunEnabledFarajn, 

typeBoolean. slzeol - } Boolean ), &inFnnEnablet3 J: 

err = NTObjectCreateE kMyFunObjeetTT), event, outObject J: 

ReleaseEvemE event ): 

GantCreatelnitEvent: 

return err; 

I 

To pass initial parameEers to an object, you need to create 
a Carbon Event with the right class and kind. You simply add 
your parameters onto that event and pass it into HlObjectCreate. 
The sort of code you see in listing 3 is exactly the sort of stuff 
Apple does in the Toolbox. Calls such as 
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Well, that was easy, Of course, your initialize handler might 
he much more complicated. As seen in the code, you should call 
through before handling the initialize event yourself. There are 
some exceptions to this, but it depends on how your object is 
set up and whether initializing the base class will cause one of 
your event handlers to be called before you are ready. But you 
should treat calling through first as the rule. 

Now, for completeness, let's add support for a couple of 
other things. First, let's add support for equality testing. If 
someone hits two references to two of your object instances, 
they could call CFEqual on them to see if they arc the same. 
CFEqual calls into the HlObjcct implementation, and that in turn 
sends a Carbon Kvem to your instance. By the time the event 
gets to you, the Tcx>lbox has already checked to see whether the 
references are identical and that the class of object is the same. 
So you know that you will he passed an instance of the same 
class as yours. All you need to do is compare your internal state 
and return the result in the event. Listing 5 shows the handler 
axle to do this. 

Listing 5: Adding the Equality Handler 


OSSt 3z u e MyC1a *sHandlen( 

EventHand 1 c rCs 11Ref inCalIRef« 

EventRef inEvent, 

void * inUBerPata ) 


OSStatus result - eventNotHandledRrr; 

MyFunObjecf object = {MyFunObject*)inllserDau: 


err = GctEventParameter( inEvent, 
kEventParamDitectObiect. 

I ypeitl Object Ref, NULL* 
sizeofC HIObjectRef ), NULL, 
tiotherHIObject): 

require„noErr( orr* MissingParameter ); 

// Now cast it to get rhe data poinLO 1 tut the other object. 

//This cast should never fail since we are guaranteed to 
// he looking at an object of the same class hy the time 
// we get here. 

other = (MyFunObjnct 1> )HlObjectDynaraicCaat C 
otherHTObJect. kMyPunObjectIO ): 
checkt other 1- NULL ): 

// compare tlve two objects'guts. For our object types, wc II 
// consider rhrm equal if their isFunEnabled sellings are rhe same. 

localResuit * ( otherOlnFunEnabled = 

object >isFunEuabled ); 

// Now store the result in the kbveiiiFaramRcsult parameter 
// as typeBoolean.TO? are done. Exit with an apprt>priate result 

Sot Event Pa r sine ter ( inEvent * 
kEvent Par amResult« 
typeBoolean. sip.eof t Boolean }, 
GlocalResul r. ): 
result ** noErr; 

I 

break; 


M iss 1 ngf'a ramete r: 
return err: 


case kEveiltHI ObjectTsRqiml; 

I 

Boolean localResult: 

HlObjcctRefotherHIObject; 

MyFunObjecf other: 

// Get the direct object. It will lx- the object we are being 
// compared m. 


As you can see, it's simple to handle the equality evenL Just 
extract the direct abject parameter and east ii to get the object 
data pointer. Then make the comparison however your class 
decides to and store the result in the event. 

There's only one more event to handle; 
kEventHIObjeGtPrintDebuglnfo. This is sent Lo your handler when 
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someone calls HIObjeclPrintDebuglnfo. Big surprise, I'm sure. 
Check on I listing 6 for how to handle this event. 

Listing 6: Adding the Debugging Handler 


OSSratiis HyClassHandier( 

EventtfandlerQLLlRef inCailRef. 
EventRet inEvent* 

void • inUserData ) 


OS Status reEiilc * oventNotHandledErr: 

MyFunObject* object " [HyFunObject •) intlserData; 


case kEven tHTObj ertPriorDabuglnfo: 

I 

fprintfE si dour. "HyFunObj ect M ): 
fprintf{ stdout* * Fun Enabled: %d** 
ob ject->isFun£tiabled ): 
result — noErr: 

1 

break: 



Fetch 


Miss!ngPararaeter: 
return ert: 


I 


Wow, That was simple* All you do to respond to this is 
print your information to sldout. Typically, you'd print the 
name of the class, and then any information under that, 
indented a bit. The Toolbox has a standard formatter for its 
output. You should in general try Lo match the look of the 
Toolbox output. In the fuLurc\ this formatter might lx? exposed 
for use by developers. 

That’s All Foots 

Well, believe it or not, you now know all you need to about 
HTOhjects. We ! ve covered the different polymorphic functions 
and shown you how to create HlObject classes and objects of 
your own design. We’ve also demonstrated dynamic casting and 
covered every event that gets sent to your HlObject from the 
HlObject subsystem. 

With this knowledge in hand, you can do things such as 
add custom toolbar items for the new HIToolbar class in Jaguar. 
You do this by subclassing the HTToolbarltem class using the 
steps shown in this article. You can also start to write custom 
views based on IllView, Remember, HlObject permeates 
everything in the Toolbox in Jaguar, so it’s a good thing to 
understand what it is and how it works. Gel out there and star! 
creating your own HlObjects! 

Special thanks to David McLeod , Eric Scblegel Guy 
EuQertony Curt Rot herh Matt Ac here t, and Bryan Prasha 

for rwfewing this article. 
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SECTION 7 


By Rich Morin 


Process Control 


ps, top , kill,... 


A recent foray into Internet Radio conflicted in some manner 
with the OSX screen saver on my desktop machine. As a result, I 
was unable to get the screen saver to go away. J tried aU of the 
usual tricks: Inning mouse buttons, moving the mouse, advancing 
to keyboard keys (eg., shift, return) and finally "magic key 
combinations" (e.g., coimiand-uption-escape). No luck. 

On Mac OS 9. my next steps would have been to try a “three- 
finger salute" Ci.e. t cummimd c ontrol-power), followed by pushing 
the reset button and if need be, pulling the plug. This being a BSD- 
based machine, however, 1 had a better solution at hand 

1 went to another machine on the local net, logged into my 
desktop machine, and killed a couple of sorely-confused puxesscs, 
I then logged out and returned to my desk, flushed with victory and 
the knowledge that I had a useful Section 7 topic in hand. 

Advance Prepakaiion 

My “remote login" trick wouldn’t have worked without a bit 
of advance preparation. OSX, for very grxxl reasons, turns off most 
“remote services", by default. 1 don't recommend turning services 
on, willy-nilly, but ftp and ssh are so handy that 1 wouldn't want to 
live without them. And, because my desktop machine is hidden 
behind a firewall, 1 consider the risk to be pretty minimal (your 
mileage may vary), 

In any case, here's how to allow remote ftp and ssh on an OSX 
10.2 machine: In the System Preferences application, select the 
Sharing dialog. Under the “Services* tab. turn on the checkboxes 
labelled "FTP Access" and "Rmote Login", 

You will also need a way to "find" your machine from the 
other one. This can lie achieved in any number of ways, including 
DNS (Domain Name System), /etc/hosts files, etc. Your network 
administrator will (or should :-) know how to make this happen 
on your local network. As a last resort, you can use your 
machines IP (Internet Protocol) address as a name. 

Logging In 

Because ftp and ssh aren’t OSX-specific tools, you am log in 
remotely from almost any operating system. This tx*ing an OSX- 


rdated column, however, 111 assume dial you're running OSX. If 
you're not, you'll have to deal with the vagaries of installing and 
starting up the needed clients on the machine you're on. On OSX, 
just start up a Terminal window and ty pe: 


% ssh <nse>@<mydesk> 

<rae> @<myd e password: 

Tire first time you do this from a given machine, you'll lx 
asked whether you trust the SSH keys on your desktop machine. 
Say yes (:-). After entering your password you’ll get a prompt from 
your desktop machine: 


<iw>tf<niydesk> H 1: 

There are all sorts of things you can do at this point, but try 
not to get too excited and do something you II regret. Think 
“delicate surgery", rather than "hack and slash". Thus, the first thing 
we want to do is find out a bit about die programs that are running 
over on the desktop machine. To do tills, we’ll use the top 
command, which displays system usage statistics and then lists the 
top processes, in terms of CPU utilization: 


<me>e<raydesk> H 2: top 

Processes: 65 total, 3 running, 62 sleeping... ]9G threads 
17:39:16 

Umtf Avg; 2.15, 1.46, 1,35 

CPU usage: 62,3% user. 37.7% sys, 0,0% idle 

SharedLibs: nun - 116, resident w 23.2M code* ... 

MeraRegions: man = 4936, resident - 15 9M * 13.0M private, ... 

VN: 4.22G + 45,8W 5363(0) pageins, 0(0) pageouts 


PTD COMMAND 
75R top 
703 tesh 
702 sshd 
701 ssb 

692 CCacheServ 
610 Finder 


XCFU TIME 
7.9% 0:38,79 

0.0% 0:00.34 

0.0% 0:00.78 

0.0% 0:00,86 
0 .0% 0:06.09 

0.0% 0:18.75 


Unlike most BSD commands, top doesn't fust run and go away. 
Instead, it refreshes its display about once a second, letting you see if 
things arc changing. When you're done viewing the display, type “q n 
(or ConrtotO and the program will terminate. Alternatively, just start 
up another Terminal window, leaving top running in the first one,,. 
The system usage statistics are a bit arcane; look at top s man 
page if you want the details. For now, just note that the number of 


Rich Morin lias been using computers since 1970, Unix since 1983, and Mac-based Unix since 1986 (when he helped Apple create A/UX 1.0). When 
he isn't writing this column, Rich runs Prime Time Freeware (www.ptf.com), a publisher of books and CD-ROMs for the Free and Open Source software 
community. Feel free to write to Rich at rdm@ptfxom. 
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processes should normally lx under 100 and that the load average 
{time-averaged system load) should lx b under five, If you see higher 
values on your machine, you may have a amaway application. 

Because tops prtxess list is sorted by CPU utilization, active 
programs tend to "bubble up*. So, kx)k near the top of the list for 
suspects. In some cases, killing off a sijngle process won't lx- 
enough; to restore my desktop to proper functionality, I had to kill 
the screen saver, the Internet Radio application, and the Finder! 

1 issued a separate kill com rmtnd for each process I 
wanted to terminate, specifying the PID (process ID). This lei me 
see and evaluate the effect of each action: 


fl C<niE>@<niyd@5k> M 3: kill 9 610 

Ik sure to get the PID right; you don't want to kill off an 
innocent application, by mistake! By die way, kill can do more than 
just terminate processes. It can send any desired * , signal 1T to one 
or more specified processes, So, for example, it can lx used to tell 
processes to check their configuration files, etc. 

If you can’t figure out which command you need to kill you 
may need to get a different view of the information. The ps 
command lists “process slums" information, in a variety of formats. 
For our present purposes, "ps awx" is a reasonable idiom: 


<me>#Cny(ifisk) M 4: ps awx 


PID 

TT 

STAT 

1 

?7 

Sis 

2 

n 

Si 

41 

77 



TIME COMMAND 
0:00.03 /sbio/init 
0:02.35 /fibin/mach_indt 
0:02.?4 kexTd 


To list the commands in a different order, just pipe together 
some commands; 

<me>#<niyd€sk> [-] 5; ps avx | sort +3 ro | more 
62 7? $s 56:09.79 ..,/WtndovServer 

PID TT STAT TIME COMMAND 

m std R+ 0:00,00 more 

993 std R4 0:00,01 sort +3 to 

610 77 S 0:18.80 .,,/MacOS/Finder -psn_0_3538945 

Transliterated, the pipeline above says to nin the output of ps 
through a line-oriented sort (sorting by the fourth column, in 
reverse numeric order), then pipe Lhe result through more (a text 
viewing command). If you know what command you’re looking 
for, of course, you can use grep: 

< m >#<myde b\0 H 6: ps awx j grop Finder 
1006 Rid R* 0:00,00 grep Finder 

610 t? S 0:18.80 .../Finder pan_0_3538945 

With tlie advent of USX 10.2, I feel more comfortable in 
recommending FreeBSD-related books to CSX users and 
programmers. There are still some differences, to lx sure, but any 
book that covers FreeBSD 4.X commands wall be a good match 
for the OSX 10.2 command set. 

Although processes are the workhorses of any BSD system, 
there are few books that spend much time on them. Quite a few 
man pages relate to processes, however, and tiie DOSSIF.R 
(www.ptf.com/dosster) volume “Processes: FreeBSD” brings them 
together in a single volume. 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Human Resources 


Adding Macintosh Resources to a 
Windows QuickTime Application 

Introduction 

Macintosh applications use resources in a wide variety of 
ways, A few of these arc: to specify their menus and menu items, 
to define the appearance of windows and dialog lx>xes 
displayed by the applications, to hold strings and other 
localizahle data, and u> store fonts, sounds, pictures, custom 
cursors, and icons, These resources — let s call them Macintosh 
resources — are stored in the application’s resource fork, which 
is automatically opened when the application is launched. The 
application can retrieve a particular resource by calling Resource 
Manager functions like GelResource and Getlcon. 

Windows applications also use things called resources for 
many of the same purposes, but these resources are noi the 
same as Macintosh resources. These resources — let s call them 
Windows resources — are stored inside the executable file (the 
.exe file) and can lx j loaded programmatically using functions 
like LoadResource and Loadlcon. Typically, an application’s 
Windows resources are defined using a resource script (a file 
whose name ends in “.re*) and are automatically inserted into 
the executable file when the application is built. 

As we've seen in many previous articles, it s often useful to 
use Macintosh resources in our QuickTime applications, whether 
those applications rim on Macintosh or Windows computers. For 
instance, when we once wanted to elicit a URL from the user, we 
called GetNewDialog to display a dialog Ihjx defined by the 
application's resources; then we called ModalDialog to handle 
user actions in the dialog box, Figure 1 shows the dialog box 
on Macintosh systems, and Figure 2 shows the dialog box on 
Windows systems. 


_ Open URL 

Enter an Internet URL to open: 


Cancel ^ f OK 


Figure 1: The Open URL dialog box (Macintosh) 



Figure 2: ihe Open URL dialog hax (Windows) 

Let's consider another example. Recently I added a 
properties panel to QuickTime Player, to display information 
about movie tracks. I constructed die panel on a Macintosh 
computer, using a text description that is convened by the tool 
Kez into a Macintosh resource. Figure 3 shows the panel on the 
Mac OS l >, and Figure 4 shows the panel on Windows, (This 
panel is not inc luded with any shipping version of QuickTime 
Player, so don't bother looking tor it.) 


Tim Monroe in a member of the QuickTime engineering team. You can contact him at monroe@apple.coni. The views expressed here are not 
necessarily shared by his employer. 
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Figure 3: The Movie Track Properties panel (Mac OS 9) 



Properties 



Background Color: 


Set.. 


R Aulo-Play Child Movie 
F* Frame Step in Child Movie 

Data Reference Type: URL 
.. pixar. com/tinloy. mov S et *, 


our Windows development environment Microsoft Visual 
Studio, to perform these steps automatically each time we 
build our application. 

Some programmers, of course, prefer to do most of their 
software development on Macintosh computers, so it's useful 
to see how to perform these steps on a Mac. Metrowerks’ 
CodeWarrior integrated development environment (IDE) for 
Macintosh supplies compilers and linkers for Windows 
targets; moreover, the QuickTime software development kit 
(SDK) provides CodeWarrior projects configured to build 
Windows applications for virtually all of the sample code 
applications. All that's missing is a Macintosh version of the 
RezWack tool. In ihis article, well see how to fill in that gap. 
First well develop a standalone application that does this, and 
then well see how to construct a plug-in for the CodeWarrior 
IDE that performs the RezWack step as part of the build 
process. By the end of lhis article, you I! know how to create 
complete Windows applications that contain Macintosh 
resources, whether you prefer to program on Macintosh or 
Windows systems. 

Before we lx:gin, I should mention that having a single 
resource description for all of our target platforms is a 
wonderful goal that is not always achievable in prat lice, at least 
if we want to pay attention to Apple's human interface 
guidelines. The reason for this is simply that the Aqua 
appearance on Mac OS X has different layout requirements than 
the “classic* Mac OS 8 and 9 appearance. For instance, button 
labels are usually larger under Aqua than under earlier systems, 
so we need to make our buttons larger. Figure 5 shows the 
movie track properties panel when displayed on a computer 
running Mac 08 X. [[ere the entire dialog box is bigger, to be 
able to contain the larger controls and other dialog items. 


Figure 4: The Movie Track Properties panel (Windows) 

The main advantage to using Macintosh resources for 
dialog boxes on both operating systems is that we can use 
the exact same resource description on both systems, and we 
can use the exact same code to display and manage the 
dialog boxes. On Windows, this magic is provided by the 
QuickTime Media Layer (or QTML), which we considered in 
an earlier article (*2001: A Space Odyssey* in MacTech, 
January 2001), In this article, I want to focus on how to 
attach Macintosh resources to a Windows application. We goL 
a preliminary taste of doing this in that earlier article, where 
we saw how to use the tools Rez and RezWack on Windows 
to convert a resource description into a resource file and 
attach it to an application. Here, 1 want to investigate this 
process in a bit greater detail and to show how to configure 


e o Test.mov Properties 


Movie Track 11 ■ Properties * I 


Background Color: 

I ~1 i« : 


2 ? Auto-Play Child Movie 
Z Frame Step in Child Movie 

Data Reference Type: URL 

pixar.com/tintoy.mov { Set.. 


Figure 5: ihe Movie Track Properties panel (Mac OS X) 
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Development on Windows 


Creating Resource Files 

Suppose, then, that we re writing a QuickTime application 
that is to run on Windows and we wxmt to do our development 
on Windows using the Visual Studio environment To make 
things as easy as possible, well construct our Macintosh 
resources by (Tearing a text file that contains a resource 
description. For instance. Listing 1 shows the resource 
description of the 1 D1TL' resource for the dialog box shown in 
Figures 3 and 4. 


Listing 1: Resource description for the Movie Track 
Properties panel 

MIA MPrt jpenks.r 

resource ’DITV (kResotircelD) t 

1 /• array DITLarray: 12 elements ‘/ 

/* m */ 

IS, 10. 25. 1321, 

SiaLicTcjct \ 
disabled. 

"Background Color:* 

L 

/■ [2] */ 

129, 12. 51. DSL 
UserItem I 

cnabled 

[ 3 ] 

130 , 14 b* 50 * 2071 , 

Button E 

enabled. 

"Set*" 

I * 

/“ [4] V 

tie. 7 , 60 , 214 }* 

User 1 lent \ 
enabled 
I, 

/* [51 •/ 

174, 7, 90, 214), 

Checkbox [ 
enabled, 

n Auto■Play Child Hovie" 


W */ 

194, 7, 110* 2141, 

ChnckBox { 
enabled, 

"Frame Step In Child Movie" 

L 

/* L71 *t 

1120, 10. 136, 132). 

StaticText 1 
disabled. 

"Data Reference Type: * 

m 'i 

1120, 132* 136, 207L 
StaticText [ 
disabled. 

"URL" 

h 

/* [ 9 ] •/ 

[140. 12. 156. 1321. 

StaticText I 
enabled. 

n v 

L 

/* [ 10 ] */ 

U3S, 146, 158, 207L 
Button t 
enabled, 

"Set*" 

L 

/ 4 (llj ■/ 

167, 10, 6S. 2151, 

Ifeerltea I 
disabled 
L 

t' tl 2 j •/ 

[ID* 10, 116, 2151* 

Userlteut [ 
disabled 

1 

) 

1: 

The QuickTime SDK for Windows provides the tool Rez* 
which converts a resource description inlo a resource file. We 
can execute this line of code in a DOS console window to create 
a resource file: 
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QuickTimeSDKVQTDevWinVFools\Rez 

-i "QuickTiiaeSDK\QTIievWin\RIncludes* i . 
MIAMPraperties.r -o HIAMPropertles.qtr 


Here, liez converts the resource descriptions in the file 
MIAMPropertiesj into resources in the resource file 
MIAMProperties.qtr. Rez looks in the current directory Q and in 
the directory QuickTimeSDK\QTDevWin\Rlncludes for any included 
.r hies. (Of course, your paths may differ depending on where 
you install the QuickTime SDK tools and ,r files.) 

'Ihe suffix '.qtr” is the preferred filename extension on 
Windows for files that contain Macintosh resources. When we 
are building an application, say QTWiredAcdons.exe, we should 
therefore name the resource file "QTWiredActions.qtr". In our 
application code, we need to explicitly open that resource file; 
to do this, wc can use the code listing 2. 


Listing 2: Opening an application's resource file 

VOnMain 

myLength = GetModuleFileNametNULL. tnyFlleName, MAX_PATH1: 
if (rayLengtb 1* 0) I 

NativePathNameToFSSpec(myFiieNai3e. SgAppFSSDec. 

kFulINativePath); 

gAppResFiie = FSpOpenResFi 1 e UgAppFSSpec. f&RdWrPern): 

If tgAppResFile 1= kliwalidFIleRerNuro] 

UaeReBFile(gAppResFilej ; 

I 


Note that we do not need this code in our Macintosh 
applications; as we noted earlier, on the Mac an application's 
resource fork is automatically opened when the application 
is launched. 

Imbedding Resource Files in an Application 

When developing and testing an application, it's okay to 
have to work with two files (the application file and the 
Macintosh resource file). But when w r e w'ant to distribute an 
application, it’s desirable to combine these two files into a single 
executable file. Tills is the job that RezWack is designed to 
accomplish, KezWack creates a new file that appends the 
resource data to the data in the executable file (and also 
appends some additional data to alert QTML to the fact that the 
.exe file contains some Macintosh resource data). We can call 
KezWack tike this: 

Qu i c kTi meS DK \ QTDs v Wi n \ To o i &\ Re zVa c k - d QTW i r e dAc t i on s . ex e 
i QTViredActiems.qtr o TenjpNaae.exe 
del QTWJredAftlanfi.exe 
ren TempNumc.exe UTWtredAct Ions,ex 


RezWack does not allow us to overwrite either of the two input 
files, so we need to .save the executable file under a temporary 
name, delete the original .exe file, and then rename the output 
file to the desired name. Once we’ve executed these commands, 
the file QTWiredActions.exe contains the original executable code 


and the Macintosh resources that were contained in the file 

QTWiredAct tons, qtr 

Rven if we have inserted the resource data into the 
executable file using RezWack, we still need to explicitly open 
the resource file at runtime; so our applications should always 
include the code in Listing 2, whether the resource data is in a 
separate file or is included in the executable file. 

Adding a Post-Link Step 

It would get tedious really fast to have to type the Rez and 
RezWack commands shown above in a DOS console window 
every time we rebuild our application. We can simplify our 
work by creating a batch file that contains these commands 
and by executing the batch file automatically as a custom post¬ 
link step. Listing 3 shows the batch file Lhai we use when 
building the debug version of the application 
QTWircdActions.exe. 


lasting 3: Rezzing and RezWacking an application’s 
resources 

MyRc&VfedtDcbug b;it 

REH *** batch pragran to embed our Macintosh 
REM 1 ‘" resources into our application file 
..\.\QTDevWitiVTools\ftez i H , ,. \QTDevWiti\RTncludes* -i . 
QTViredActions,r q QTWiredActions.qtr 
. \QTEeyWin\Too Is \ RezWack d . VDebug\QTWi redActions.cxe 
-r QTWiredActions.qtr *o .\Debug\TEMF.exe f 
del .\Debug\QTWiredActions,exe 
REM + now rename neu file to previous name 
ren .\Uebug\TEMP.exe QTWI redAct 1ons.exe 


You’ll notice that the paths lo the Rcz and RezWack tools 
are relative Lo the location of the batch file, which we keep in 
the same folder as the Visual Studio project file; you may need 
to edit this file to set the correct paths for your particular 
foi de r a rra nge me n i. 

We cm tell Visual Studio to execute this file as a custom 
post-link step by adjusting the project settings Figure 6 shows 
the appropriate settings panel 


JUJU 



Figure 6; Setting a custom post-link step 


30 


Human Resources 


MacTech • October 2002 























TM 


Development on Macintosh 
So what does RezWack actually dot We already know That it 
adds Macintosh resource data to a Windows executable file. But 
we need to uncover a bit more detail here if we are to be able 
Lo write a tool that performs resource wa eking on Macintosh 
computers. Here's the essential information: RezWack creates a 
new file that logins with the data in the Windows executable 
file, followed immediately by the Macintosh resource data, 
padded to the nearest 4K boundary; this is all followed by some 
RezWack tag data , Figure 7 illustrates the structure of a file 
treated by RezWack; let's call this a wackedfile. 


Application data 


Mac resource data 
Padding 

RezWack tag data 
Figure 7; The structure of a wacked file 



Hie RezWack tag data is a 36-byte block of data that 
describes the layout of the wacked file. It specifies the offset of 
the executable data from the beginning of the file (which is 
usually 0) and the size of the executable data; it also specifies 
the offset of the resource data from the loginning of die file and 
the size of die resource data. The tag data ends with this 12-byte 
identifier; “mkQuicki'ime™". (What's the “mk7 ! strongly 
suspect that they are die initials of the engineer who 
implemented the RezWack tool.) 

The idea here is that QuickTime can look at the last 12 
bytes of a Windows executable file to determine whether it 
contains any Macintosh resources. If it does, then QuickTime 
can look at the last 36 bytes of the file to get the offset into the 
file of those resources and the size of the resource data. 

Let's define a couple of constants dial we can use to help 
us in the wacking process: 

^define kRezVackTag ^rckQuickTine 11 * 

^define kRezWaekTagSize 12 

Then we can define this data structure for the RezWack Lag data: 


lypedef struct RczWackTagBata l 

//mustbe'data' 

UInt32 

fUataTag; 

UInt32 

fDataOffset: 

// offset of binary data 

UInt32 

fDataSize; 

// size of binary date 
// must be W 

UInt32 

fRsrcTag: 

UInt32 

fRsrcOffeet; 

// offset of resource data 

UTnt 3 2 

fRsrcSize; 

// size of resource data 
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char fWackTagfkRezWackTagSize] ; 

I RezWackTagData, *RezWackTagDataPtr; 

Well use this litter, when we finally get around to building 
wackcd files. 

Setting up a Droplet 

Our current goal is to develop a standalone application — 
let's call it "RezWack PPC" — that we can use as a droplet. Thai 
is, well compile our Windows code using CodeWarrior on the 
Macintosh and then drag the executable Kile created by 
CodeWarrior onto our droplet, which finds Lite appropriate 
resource Hie and creates a new file containing the executable 
data, the resource data, and the RezWack tag data* 

We want the final wackecl file to have the standard '\exe H 
suffix, so we need to tell CodeWarrior to generate an 
intermediate executable file with some other suffix, (Remember, 
RezWack won't overwrite either of iis input files and so neither 
should we.) Let's use the suffix ".bin”, as shown in Figure 8, 


80 
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Figure 8: Setting the intermediate file name 

Our droplet should accept these binary files, look for a 
resource file with the suffix '\qtr\ and then create the final 
wackcd file with the “\exe" suffix. To make RezWack PPC act 
like a droplet, we need lo modify the function 
QTApp_HandleOpenDocumentAppleEvent, Listing 4 shows our 
new definition of this function. 


listing 4: Handling files dropped onto RezWack PPC 

Q IX| >|»J liimtkt >| hi i Docufilen UV|>|>k‘ live ni 

PAKCAL_RTN OSErr QTApp_HandleOpenDo£mneiiTAppleEveiit 

{const AppleEvent *thfcWessage, AppleEvenr 'theRoply, 
long theRefcon) 

I 

ragEna unused(th^RopIy, thoRefcon) 


long 

long 

AEKeyword 

AEDescList 

long 

DescType 


myIndex; 
myltetnsinList: 
myKeyWd; 
myDocLiet; 
myActualSize: 
myTypeCode: 


FSSpec myFSSpec; 

OSErr mylgnoreErr “ noErr; 

OSErr myErr “ noErr: 

// get the dket parameter anti put it imo myOodist 

myDoetist.dat a Handle * XtHX: 

myErr 3 ARGciParattDejscUfoeMessfige, keyDlrectObject, 
typeAEList, tonyDoeList): 

// count the descriptor records in ihc list 

if [myErr — noErr) 

myErr ^ AECountIterns(&rayDoeList, imyltemsInList): 
else 

mylterasInList = fl; 

// open each specified file 

for (tnylridex “ 1; my Index mylternsInList; raylndex-H-) 
if (myErr = noErr) f 

myErr = AEGetHthPrrUmyDocList r mylndex. typsFSS, 
imyKeyVd. fonyTypeCode, (Pt r) &myFSSpec t 
sizeof(myFSSpeei. imyAetunlSiza); 
if (myErr — noErr) I 
FTnfo wyFinderInfo; 

if verily that the file tyjx- is JsWintiinaryFtfcTypc or kWlnLlhraryHtkTvpe 

myErr = FSpGetElnf a UinyFSSpec. knyFinderlnfo); 
if {myErr noErr) 

if {(myFinderlnfo.fdType “ kVinBinaryFileType) 

| (myFinderlnfo.fdType “ kWInLibraryFiloType)) 
cfrRW_Croat<»RczWnckedFI loFroinHrnery [fcmyFSSpec); 

I 

I 


If (myDoclist.dataHandle) 

raylgnoreErr ~ AEDisposeDesc(&jnyDaeListJ: 

QTFrame Quit Framework ( } ; // act like a droplet and dose automatically 

return(myErr); 


As you can see, we look for files of type KWinBinaryFleType 
and kWin LibraryFileType, which have these file types: 

^define kVinBinaryFileType FOUR ETtAR_OODE ( } DEXE ’) 

Refine kWinUbtaryFiUType FQDR_CHAft_CODE('IDLE') 

When we find one of these types of files, we call 
GTRW.CreateRezWackedFifeFromBinary to do the necessary 
resource wacking. Notice that we call QTFrame_QuitFramework 
lo quit the application once we are done processing the files 
dropped on it. 

Wacking the Resources 

Listing 5 shows our definition of 
QTRW_CrealeRezWackedFileFromBinary: this function simply 
configures two additional file system specification records (one 
for the Macintosh resource file and one fur the final wackcd 
file) and then calls another function, 
QTRW RezWaekWinBinaryAndMacResFile, to do the real work. 
As indicated above, we assume that the resource file has ihe 
same name as the binary file but with the *\qtr” suffix and that 
the final wackecl file has the same name as the binary file but 
with the ".exe“ suffix, (I II leave it as an exercise for the reader 
to implement less restrictive naming for (he three files we need 
lo work with.) 


Listing 5: Setting up names for the resource and wackcd 


files 


Q'IW_Cf«tcRczWid;edFaeFfonaJiiun 


32 


Human Resources 


MacTecii • October 2002 


































The Key is in Your Hands! 


Does your dongle do all this? 


Software Goes Online 

Electronic Software Distribution - safely protected by WIBU-KEY. 

Web Remote Programming 

Reprogram the WIBU-BOX hardware at the customer's site directly 
via the Internet. 

Web Authentication 

Secure authentication via a two-way-encryption. 

Pay-Per-Use 

Usage dependent accounting. 

MacOS9&X 

WIBU-KEY supports Mac OS, Windows and heterogeneous networks. 

► Yes? Then you are already using WIBU-KEY! 




► No? Then order your Test Kit 

at 1 - 800 - 986-6578 

You will find more information at 
www.griftech.com 


.^GRJFFIN 

' > Ten u klrtl I U - ( L i 


TFCHNOi OCIES 


USA. Canada: Griffin technologies. LLt 

phone: (785) B32-2Q70 fax: (785) B324TW 
email: Mle5@griftech.com www.griftcch.com 


or visit our booth at... 

a COMDEX 

Fall 2002 booth 821 


wibusvsthmsag 

76137 Karlsruhe. Germany 
WtBU-SYSTEMS USA, Inc 
Seattle, WA 98101 
email: info@wibu.com 


UIBU 

SYSTEMS 


...and see our products 



www.wibu.com 


Test Kits also available at: 

Argentina info&satrekl-group coin, Australia timone tckeilr-Owibocom, Belgium ■wvibuOimpakt.be. Croatia anesVanes hr, Denmark teanbdsnbit dt, Egypt 
esafwattitodec com .eg, Finland fmebyie^tinebyie.com, France lnfoktetoi.fr, Hungary mfoOmrsoft.hu, Japan mfoOstmGar1a.to.jp. iordao, Lebanon 
starsofttteybcrifl.nirt.lb, Korea d-hkimmOwlbu.co.kr, Luxembourg wibuiftimpflkt.be, Netherlands wthofllmpakt,be, Portugal r1utjil9dubil.pl, Syria 
starsofteryberianet lb, Thailand prifechaOdptf-lh com. United Kingdom inftjVcodewQrk com, USA salesWgrlftiJCh com 
















OSEr r QTRW _CreateRe2WackedFileFromBinary 
(FSSpecPtr theBinFSSpecptrJ 

l 

FSSpcc nyReaSpec; 

FSSpec myExeSpec; 

OSErr myErr * paramKrr; 

if (theBinESSpecFtr = NULL) 
goto bail: 

// currently, we suppose that the MucinLush resource fik has the same name as ihc 
// binary, but with ‘qtr* flk name extension 

myResSpee ” 'thefii riFSSpecPtr ; 
uyResSpec-name [my ResSpec.namc[Q] T 2] = 1 q 1 ; 
royResSpec: Kname ImyResSpec,nomie[0] I] " "t 1 ; 
rayResSpec.name[rayKesSpec.name(0] 0] ™ 1 r'i 

// ouTcmiy. we suppose that 13it Windows executable flic has the same name as 
the 

// binary, hut with "cxe" file name extension 

myExeSpec ** *thoB1nFSSpecFtr: 

myExeSpec pTiame [myExeSpec .name[D] ?.] " 
myExeSpec-naiie LJtiyhxeSpec .natuefO] 1] * *%*', 
myExeSpec .narae [myExeSpet ,*iattie (0) - 0] - *&*', 

my Err " QTRW KezWackWinBinaryAndMacResFUe ( 

tbeBinFSSpecPtr * AmyResSpec, itnyExeSpec); 

bail; 

return(myErt)j 

I 


FSC1ose(myReaFile); 

jnyErr - FSpOpcnDF(TheResFSSpecPtr, ffiRdFerm, kmyResFile): 
if (myErr !- nuErr) 
goto bail; 


Once we've got all three files open, it's really quite 
simple to construct the wacked file. We copy the executable 
data from the binary file into the output file and copy the 
resource data from the resource file into the output file. Then 
we pad the file data to the nearest 4K boundary, as shown in 
Listing 7. 

Listing 7: Padding the executable and resource data 

QTRW RezWackWi niton AnilMac ResIlk 

mySizeQfExe = mySizeQfhln + mySlxeOfRes; 

while ((mySizeOfXxe + sizeof (tny TagOnt a) ) % (4 * 1024) != O) 

( 

char myChar ® * \0 1 ; 
myStzc = 1; 

myErr - FSWrtte{myRxcFile» AmySixe. fcinyChair): 
if (myErr I* noKrr) 
goto bail; 
mySizeQfKx&++: 


QTRW^RezWackWinBinaryAndMacResFile is the key function 
in RezWack PPG, It takes the binary file created by Gxle Warrior 
and the Macintosh resource file and then creates the desired 
wacked file. First, it creates an empty file, having the same type 
and creator as the original binary file: 

FSpCetFlfifo UheBinFSSpecPtr, ArnyFilelnfo] ; 
FSpCreatettheExeFSSpeePtr* myFileitifo.fdCrcAtor* 
rayFilelnfo,fdType, 0); 


Then QTRW_RezWackWinBinaryAndMaeResFile opens all 
three relevant files, using FSpOpenDF to open the binary and 
wacked files, and FSpOpenRF to open the resource file. Actually, 
we want our droplet to lx, 1 a bit more flexible about handling 
resource files; it s possible for resource data to lx 1 stored in a 
data fork of a file, particularly if the resource data was created 
on a Windows computer (perhaps using the Rex tool). So first 
well attempt to open a resource fork having the appropriate 
name; if we can’t find it or if its length is 0, well attempt to open 
a data fork having the appropriate name. Listing 6 shows the 
code that accomplishes this. 


Listing 6; Opening the resource file 

QTRW RezWnt k Win lii nary And M aeKesFik 

myErr - FSpO|renIF(theResFSSpecPt r, fsRdPtM-m, kmyResFi 1«); 
if (rayErr != noErr) t 
isyTryDataFork * truer 
I else I 

// it's pusMbk; th.tt the resource lurk exbls but is (J-lcnglh; if sip. try bit- data fork 

GotEOFfmyRflfrFtl fc, tatySigeOfRes); 

ff (myStxeOfRes “ 0) 
myTryDataFork = true; 


if (tayTryDataFork) t 

// dost 1 the open resource hk (,presumably a Okngth resource fork) 

if (fltyResFile t» *1) 


The last thing we need to do is append the RezWack tag 
data Listing 8 shows the code we use to do this. Notice that the 
tag data must be in big-endian byte order (as is typical for 
Q u i ckTi me- re I at ed da La) t 


Listing 8; Appending the RezWack tag data 

QTR W_Rcz Wack Wi nRinaryAndMacResFile 

myTagBata.fDataTag = EndianU32_NtoB{ Flong) 'data*) ; 
myTagData-fDatsOffset ° 0L; 

myTagDara.fBataSize - SndianU32„NtoB(mySizeOfEin); 
rayTagDaia.fRsrrTag - KtidiantM2 NtoB( (long) 1 rare*): 
myTtagpata. fRsrcQfTsel End liiriE^2 NToB(mySizaOfBin); 
rayTagOata. fRsrcSim? = EridiauUl?„NloR(myMzeOfRGfO; 

Strncpy (myTagData.fWackTag. kRefcWaekTag, kRozWackTagSize): 

raySize = sizeof(myTagDara): 

rayErr = FSWrite(rayExGFile, imySize, &ayTagData); 

And we’re done! Listing 9 shows the complete definition of 
QTRW_RezWaGkWtnBinaryAndMacResRe. 


Listing 9: Creating a wacked file 

QTRW Kr / Wark Win lii riiiiyA nt iMavJtrsFik* 

OSErr QTRW RezWackWinBinaryAndHacResfi U 

(FSSpccPn tbeBinFSSpecPtr, FSSpecPtr thGReeFSSpecFtr. 
FSSpx?.cFtr rbeExeFSSpflcPtr) 

I 


FInfo 

short 

short 

short 

long 

long 

long 

long 

long 

Handle 

Re z W ackTa gDa t a 

Boolean 

OSErr 


myFlleln To; 
myBinFile = ); 

myResFile ” 1: 

myExeFUe = -1: 
mySizeOfBin * Ok: 
mySixaOfRes - 0L; 
nySizeOfExe “ 0L: 
nySize * 01.: 
royUata = 0L; 
iiyHandle ” NULL: 
myTagData; 

myTryDataFork * false: 
ayErr “ paramErr; 


// m,ik(‘ sure wc dre passed three non-NUtl FSSpctRr s 
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if ( CtheBluFSSpecPtr = NULL) 

I I (theResFSSpecPir NULL) 

| (theExeFSSpecPtr ” NULL)) 

goto bail: 

// gti the creator and file type of the binary fitc 

myF.rr " FSpGetFInfoUhcBinPSSpecPtr. frmyFileliifo); 

If (ayErr != noErtr) 
goto bail; 

// create Ute Raid executable die 

myErr - FSpCreateftheExaFSSpftcPtr, ayFI lelnfo. fdCreatox. 
myFilfiTnfo. fdTypc, 0); 

if {(myErr I" noErr) && (myErr dupFNErr)) 
goto bail; 

my Err = FSpOpenDFUheExeFSSpecPtr. fsRdWrPerm. 

kmyExeFile) : 
if (myErr != noErr) 
goto bail; 

// open the resource file it s possible ikit the resources are Moral in tile data fork 
// (pameiihifiy if the resource file was t>nill on Windows); so make sure we've got a 
// rton-Olengtli resource file 

myErr = FSpQpenRF(theResFSSpecPtr, fsRdPera, kmyResFile)j 
if (myErr !* noErr) S 
tnyTryDataFork “ true: 

I else I 

// its possible that tile resource fork exists bur is 0 length; if so. m the data fork 

GetEOF(myResF S1 C. SmyS UeODte©) : 

If finySIzeOfRes — 0) 
my Try Da Lit Fork = true; 

1 

if (myTryDataFork) I 

// dose the open resource file (presumably a tUengih ri se Hirer fork) 

If (myResFile t w I) 

FSC1ose(myRonFiie): 

myErr - FSpGpenDFftheResFSSpecPtr. fsRdPorm. 

imyResFiIs): 
if (myErr ! =• noErr) 
goto bail: 

\ 

myErr - FSpOpcnUF(theBioFSSpecPtr, fsRdPerm, 6myBinFile): 
if (myErr 1= noErr) 
goto bail; 

// copy die Innary data into the final executable file 

myErr “ SetEGF£TnyE*flFile t 0); 
if (myErr != noErr) 
goto bail; 

myRt i “ GetEaF(myBitiFiks imySi^eOfBinJ : 
if (MyErr 1= noErr) 
goto ball: 

myliamUe - NewHnndleClear(tirySizeDfBin): 
if (myHandie = NULL) 1 
myErr = MeitiErrorU : 
goto bail; 


myErr = SetFPbstmyBinFi lc-, fsFromStart. 0): 
if (myErr 1= noErr) 
goto bail: 

myErr - FSReadfmyBInFi U*» kmySizeGffliti* ‘myHandle); 
if (wyHrr I- noErr) 
goto ball; 

myErr = SetFPosCmyExeFile. fsFromStart, 0): 
if (myErr I* noErr) 
goto bail: 

myErr = FStfr \ teEmyExoFile, &mySizeOfBin, *myHandle) : 
if (myErr noErr) 
goto bail: 

FSClose(myBinFile); 


Disposeiiandle (myHandle): 

// copy the resource data into the final executable file 

myErr = GetEOFftnyftefiFile. AmySi zoOfRes); 
if {myErr 1= noKrr) 
goto ball; 

myHandle - NewHandleClest(mySizeOfRea); 
if tmyHandle — NULL) ( 
myErr ■= MemErrorO: 
goto bail: 


myErr " SetFPa${myResFlle. IsFromSlart T 0}; 
if (tnyErr !“ noErr) 
goto bail; 

myErr - FSReacHmyResFile, SmySizeOfRes h *myHandle): 
if (myErr N noErr) 
goto bail: 

myErr - FSWrltt? (raybxeFile * SrmySizeOfRes* *myHandie): 

If {myErr !- noErr) 
goto bail; 

FSClose(rayRosFile): 

DisposeHandle(myHandle): 

H pad the final executable file so that it ends on :i 4K boundary 

mySI zoOfF,xo “ myE i zv () j Bin + mySi zeOt'Re8: 

while {(mySizeOf Exe + slzeof (tnyTagData)) % (4 * 1024} 

I- 0) I 

char myChar * 1 V0 1 ; 
my Size ** 1; 

myErr - FSWr1 to(myExeF11e* &mySize. imyChar): 

If (myErr !” ruiKri) 
goto bail; 
mySii£e0fExe++i 
I 

// .Kkl on the special Re/Wack tag ihu 

myTsgData.fDarnTag indiantl1?_Ntob( (.longi 'du i <i 1 ; 

jnyTagData.fDataDfFsot ~ 01,; 

nyTagData*fDataSize = EndiauU32_NtoB(my£iset)fBirc): 
myTagData.fRsrcTng ” EndianU32_MtoB{(long) 1 rsrc*): 
myTagData ,OtsrcOff set - EndianU32 NtoB(mySizeOfBin); 
myTagData.fRsrcSlze - EndianU32 NtoB(mySizoOfRes); 

© t tnepy (myTa gD a 1 a * f¥a c kTa g. kRe zWa r.kTa g, 
kRezWackTagSiXp): 

mySize = aizeof(myfagflata); 

myErr * FSUrl teftnyExeFile, SitnySize< ^myTagData); 

FSClose(myKxeFile); 
bail: 

return(myErr): 

1 

CODCWAKRIOR PLlfCi-lNS 

Our KezWaek PPC droplet is a great little tool, but tilings 
would he even more convenient if we could get Code Warrior 
to perform the resource wucking automatics I ly— in rhe same 
way that we earlier added a fxist-link step to our Microsoft 
Visual Studio projects to run the Rez and RezWack tools 
automatically each time we build an application rhat uses 
Macintosh resources. Indeed this is possible, but ii's 
significantly more complicated than just writing a batch file 
containing a few commands that are executed at the proper 
time* We need to write a CodeWarriorfAug-in, a code module 
that extends the capabilities of the CodeWarrior IDE* to do this 
post-link step for us. We also will want to write a CodeWarrior 
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settings panel plug-in y to allow us to specify the names of the 
resource file and the linn I output file. Figure 9 shows our 
settings panel. 


6 @ Qt W i redact ions Win Settings 



Figure 9: 7fte RezWack settings panel 

In this section, well take a look at the major steps involved 
in writing a CodeWarrior post-linker plug-in and a settings panel 
plug in for whacking Macintosh resources into Windows 
applications. We won't have space to step through the entire 
process, but Ml try to touch on the most important points. 
Thankfully, most of the hard engineering is already done, for 
two reasons. First, well be able to use the 
QTRW RezWackWinBinaryAndMacResFile function defined above 
(Listing 9) virtually unchanged within our post-linker plug-in 
code. And second, Metro works provides an SDK for writing 
CodeWarrior plug-ins that includes extensive documentation and 
several sample plug-in projects. Most of our work will consist of 
adapting two of the existing samples to create a RezWack post¬ 
linker and .selling panel. 

Writing a Post-linker Plug-In 

Lei s begin by writing a post-linker plug-in. The first thing 
to clo is download the CodeWarrior SDK from the Metrowerks 
web site. (See the end of this article for the exact location.) I 
installed the SDK directly into the “Metrowerks CodeWarrior 11 
folder on my local machine. Then I duplicated the sample 
project called “Sample..Linker". (There is no sample post¬ 
linker project, but it will be easy enough to convert their linker 
into a post-linker) Let’s call our new project 
“CWRezWack.Lin ke Once we rename all of the source code 
files and project files appropriately, well have the project 
shown in Figure 10. (The file CWRazWack.rsrc is new and 
contains a number of string resources that we’ll use to report 
problems that occur during the post-linking; see I he section 
“Handling Post-Link Errors' 1 below.) 
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Figure 10: The RezWack post-linker project window 

The sample linker project provided by Metrowerks includes 
lx>th Macintosh and Windows targets, but 1 have removed the 
Windows target for simplicity; after all, we don't need a RezWack 
post-linker on Windows. As you can see, our project contains 
two source code files, CWRezWack.c and CWRezWackUtlls.cpp. 
Iliese ate just renamed versions of the original Sample_Ltnker.c 
and SampleUfecpp We won't modify CWRezWackUtlls.cpp 
further, except to update the included header file from 
SampleUtils h to CWRezWackUtils.lL 

In the file CWRezWack.c, we want to remove any code 
that supports disassembling. Well remove the entire 
definition of the Disassemble function as well as its function 
declaration near the top of the file. Also, we'll rework the 
function CWPIugin GetDropInFfags so that it looks like 
Listing 10. 

lasting 10: Specifying the plug-in capabilities 

CWPhigin CictDnipInPta^s 

CVFLUGIENTRY(CWPIugin GetDropInFIags) 

(const DroptnFlags** Flogs, long* flagsSize) 

I 

Static const DropTnFlagj; sFlags = I 
kCurrentDrapint 1 ] JigsVersian , 

CWBROPTNLINKERTYPE, 

nROPlNCOMFlLERLlSKERAPIVERSTON.T, 

IsPostLinker | eantDisas&einble. /* we are a post linker *t 

0. 

DRO PINCOMF T LERLINK E RA PIVER S T ON 

I; 

* flags = JtaFlags; 

•flagsSize ~ sizeof (sFlags); 

return cwNoErr: 

i 

Originally, the fourth line of flags was just 
JinkMultiTargAware- since weVe not supporting Windows or 
disassembling, and since we are building a post-linker, weVe 
changed dial to isPostLinker I cant Disassemble. 
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The next important change concerns the routine 
CWPtugin GetTargetLisL shown in Listing 11, As you can see, 
we indicate that our post-linker applies only to applications built 
for the Windows operating system, since there is no need to 
RezWack Macintosh applications. 

Listing 11: Specifying the plug in targets 

C WPIugin_flet Titr^CtOst 

CWmiGINJMRY (CWPluRin.GecTa r get List) 

(const CWTargetUst*' targetList) 

I 

static CWDataTypci jjCPEJ * targetCPUAny: 
static CWDataTypa sOS = targatOSWindows; 
static CWTargoiLiijit sTargetList ^ 

IkCurrimCWTatgetListVerfiion, 1* &sCPLf, l t fcsOSI; 

•targetList *= ieTargatUst: 

return cwNoErr; 


The main function of a Code Warrior plug-in is largely a 
dispatcher that calls other functions in she plug-in in 
response to various requests it receives. Here we need to 
make just one change to die sample plug-in code, namely lo 
return an error if our plug-in is asked to disassemble some 
object code: 

case reqMsassf'Jihle: 

t dLsitvscmbk object code for a given project file 7 
result “ cwErrRequestFailed: 
break: 

The only request we really want to handle is the reqLink 
request; in response to this request, we call die Link function 
defined in Listing 12. 


Listing 12: Handling a Jink request 

Jink 

static CVResuit LinktCWPlugiuContext context) 

I 

CWTargetltifo targetinfo: 

CWResult ^rr; 

FSSpec fileSpec; 

// net the current linker target 

err * CWGetTargetInfo(context„ Ltargetlnfo); 

// get an FSSpec from the CWFileSpee 

ConvertCWFileSpecToFSSpye ((targetInfo.out file. 

AfileSpeeh 

// m\i I Mac resources to t biker targe I to create llnal Windows executable 
if (err — ewNcErr) 

err ** CreateEeaWackedFi i cFi umMnary (context. 
ifileSpoc] ; 

return (err): 


CWGetTargetlnfo returns information about the link target 
(that is, die file created by the CodeWarrior linker); we can 
extract a file system specification from that information using 
the utility function ConvertCWFtleSpecToFSSpec, Then we 
pass dial specification to GreateRezWackedFileFromBinary 
Finally we are on familiar-looking ground once again. The 


definition of Create RezWackedFileFromBmary is shown in 

Listing 13 

Listing 13: Getting names for the resource and wacked 
files 

('rea u-Rez WackcdlikFmm Binary 

OSErr Cre3T^Re^WackedFileFromBinary 

(CVFluginContext context. FSSpecFtr theBinfSSpecFt;r) 

« 

FSSpee myResSpec: 

FSSpec ffiyExeSpec; 

CWHemHaiidleprefsHand: 

SamplePref pr^fsData: 

SampiePref 'prefsPtr: 

short errMsgNum: 

CWRepult err; 

OSErr myErr — paramErr; 

iF UheMnFSSpecFtr — HULL) 
goto bail; 

// insult a default name for die output file 

myExsSpec “ *thuBinFSSpecFtr; 
ayExeSpec,tiame [myExeSpec .name [Q] 2 j * 'e 1 ; 

uiyExoSpee.namc IrayExeSper.nnmo [0) - 13 “ f x': 
myKxeSpec.name [myExeSpoe , name [0] 0] “ f e 1 ; 

// install a ddauit music for tlie resource filer 

myResSpec = *thoRLnFSSpocFtr; 
my Res Spec* name ftoy ResSpec, name |0) 2] ~ 'tp; 

myKesSpeo .name1 myites Spec .name [0) 1J ** ’t*; 

myResSpcc ,nameImyResSpec.name [0] Oj - 1 r*: 

// lo.ul die panel prvfs rod get ilie specified names for the resource ami output 
iiIcn 

err = CWGetNamed Preferences (context. kSamplePanelNatae, 

&prefattend); 
if (err “ ewHuErr} l 

err = CVLockJJemHstndte ( context . prefattend. false, 

(void* * UprefsPtr): 
if (err = cWNoErr) t 
prefsPata * *prfifsPtr: 

royExeSpecMiamelG] = BcrlenCprefnOato.oiufile) ; 
BltickMovcfla ui (pref sData. outf i 1 v , uiyExe Spec .name * I, 
myExoSpec, name [ 01); 

myRcsSpec,name[0] “ atrlenlprefsData. resfUe) j 
BIoekHoveData(prefsDa;^*resfile. myResSpee . name + 1. 
myRosSpec * name f 0]); 

GWUnlockMemHandle (context . prefaHand); 

| 

t 

myErt * ReKWaekWinBinaryAndHacReuFilettheBinFSSpecFrr. 

^myResSpec, AmyExi^Spec, &er rMsgNum); 
if (myErr t= tioErr) 

ReportError(context . errMagNua); 

bail: 

return(wyErr): 

\ 


The cent nil portion of CreateRezWackedFiieFromBinary 
retrieves the names of the resource file and the desired output 
file from our custom settings panel; then it calls 
RezWackWinBlnaryAndMacResFiie (which is largely just a 
renamed version of QTRW RezWackWinBtnaryAndMacResFile K 
in theory, we could omit the code that retrieves the resource 
file name and the output file name and just use hard-coded 
extensions, like we did in our RezWack PPG droplet. This 
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would relieve us of having to write a settings panel plug-in, 
hut it would provide less flexibility in naming things. Let's do 
things the rig lit way, even if it means a hit of extra work. 

Believe it or not, that’s all we need to change in the sample 
linker to make our RezWack post-linker. We finish up by 
building tire post-linker plug-in and installing it into the 
appropriate folder in the Code Warrior plug-in directory. The 
next time we launch CodeWarrior, we'll lx. 1 able to select our 
post-linker in the Target Settings panel of a Windows application 
project, as shown in Figure 11, 
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Figure II: The jn>st-linker menu with our RezWack plug-in 


Handling Post-link Errors 

You may have noticed, in Listing J3 T that 
RezWackWinBinaryAndMac Res File returns Lin error code through 
the errMsghJum parameter. For instance, if the attempt to ojxin the 
specified resource file fails, then RezWackWinBinaryAndMaeResFile 
executes this code: 

if (ayErr noEtr} I 

•errMs&Nun = kOpenResError: 

goto bail; 


II CreateRezWackedFiieFromBinary secs that errMsgNum is 
non-zero, then it calls a function ReportError to display an 
error message to the user; a typical error message is shown 

in Figure 12. 
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The kOpen Res Error constant is defined in our header file 
CWRezWack.h; here's the complete list of error-related constants 
defined there: 


JMefiiie kfixeCr^atoError 1 

tfdef Ine, kRxeCreateErrori.2 2 

|define kOpenKxeError 3 

^define k0petiExeEi:ri>irL2 4 

^define kOperiResError 5 

(Mefine k0penResErrorL2 fi 

ffdetine kOpeuBittError 7 

#de£ine kOpenBinErrorh?. 8 

^define kGetHemError 9 

^define. kGRtM^mEirurL^ 10 

^define kWrileKxeErtor 11 

Idcflnc kWrileEx«Ei:rorL2 12 


These are simply Indices into a resource of type STR# that 
is contained in the file CWRezWackJsrc. Notice that each error 
has two corresponding string resources (for instance, 
kOpenResError and kOpenRe$Errorl_2), These two strings provide 
the messages on die two lines of each error message in the 
‘ Errors & Warnings' 1 window (for instance, "An error occurred 
while Lrying to open the resource file/ and “Make sure it has the 
name specified in die RezWack panel/). 

Listing 14 shows our definition of ReportError The key 
ingredient here is the CWReportMessage function, which takes 
two strings and displays them to the user in the "Errors & 
Warnings" wrindow. 


Listing 14: Reporting a post-linking error to the user 

ReportError 

void RoporlError (CWPIuginContext context, short errMfsgNum) 

I 

Stt25S pErrorHsg: 

char cErrorMsgU[2561: 

char cErrorHsgL2[256]; 

Get!ndStrin&(pErrocMfig. kErrorStrUL errMegNunp: 
if (pErrorHsg(0] 0) 

I 

BloekHoveData(&pErrorHsgIl], icErrorMsgLl, pErroiMsgEO]); 
cErrorMsgLl[pErrorMsg[0]] - 0; 

1 

GetIndString(pErrorMEg, kErrorStrlO, et tMtgfJura + 1) ; 
if (pErrorMf!g[D] I” Oj 
I 

BlockMoveData(6pErrotH!»g[i j, 6cErrorKsgL2 . pErrortisg [0]): 
cKrrorKsgL2[pErrorMsg[0]] = 0: 


CWReportHessage(contRXt, MULL, (char*)6rKrrorMsgLl. 
(char*)licErrc5rHflgL2. mcasagotypeKtror♦ 0): 

I 


Writing a Settings Pane) Plug-In 

The final thing we need lo do is construct our settings panel 
plug-in (also called a preference panel plug-in), which displays 
the panel we saw earlier (Figure 91 and communicates the 
settings in that panel to our post-linker when it calls 
CWGetNamedPreferences (as in Listing 13) Once again, well 
clone the sample settings panel project and rename things 
appropriately, to obtain ihe project window shown in Figure 13 


Figure 12: A post-linking error message 
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Figure I j: The RezWack settings panel project window 

The layout of the settings panel is determined by a 
resource of type PPob in die resource hie RezWack. rsre. Figure 
14 shows the RezWack panel as it appears in the Constructor 
application. 


0 0 0 Layout 129, ‘RezWack Panel" 

Set the resource file and the output file: 1 

Resource file;* 

Output Fite' 4 


Figure 14: ihc RezWack settings panel itt Constructor 


Our RezWack sellings panel contains only five items, which 
we can identify in our code using these constants: 


e.mm ( 

kStatlcTexi = 1* 

kResFileLabel* 
kKesFileEditBox. 
kGutputFileLabel p 
kOu t putFileEd11Box 

1; 


Most of the changes required in the sample settings panel 
plug-in code involve removing unneeded routines, which 1 
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won't discus* further The two key functions are the PutData 
and GetData routines, which transfer data between the on¬ 
screen settings panel and an in-memory handle of settings 
data. Fur uur Re/Wack seLtings panel, the data in memory has 
this structure; 

lypedel struct SamplePrel I 
short version; 

char outfilelkFileNa&eSize] : 

char resfile [kFileNameSize] i 

I SauplePref, “SatoplePreflUndle; 

(Take a look back at Listing 13 to see how we use the 
outfile and resfite fields when building a wacked file.) 

Listing 15 shows our version of the PutData function, 
which copies settings information from the handle of settings 
data to the settings panel. 


kQutputFileEditBox, outnane. 
sizeof(thePreferencee.outfile)); 

THROW IF ERR[result}; 

// apparently non-printing characters can squeeze their way into the dialog box, 

// so winnow them our,,. 

for (1 = 0. j = 0; i < strlen(outname)i i++) 
if (isprint(outname(i|)} 

thePreferences. outf lie EJ++] - outname Ill: 

thePreferences.outfile[J] = 0; 

result = CWPaoelGetItenTexi(context, kResFilefidliBox, 
resname, sizeoftLheFreferences.resfile)); 

THROW_IF_ERK(result); 

// apparently non-priming character* can squeeze their way into die dialog box, 

// ,so winnow them out... 

for [i = 0. j - 0: i < fitrlon(resnani£}: 1++) 
if (isprint[rosnamn[13)) 

rhePreferences^resf l!e[j++] “ resuaaielij; 

ihePreferenees*resfile[jj * 0: 


Listing 15: Copying sellings data Into the settings panel 

PutData 

static CWResult PutData (CWPlugmContext context) 

I 

CWKcsull result - cwNoSrr; 

CWHcdtaudlemenillundle * NULL; 

SamplePref thePrefetences: 

try 

I 

// (kt a pointer to the current prefc 

result “ (GetThePreferenees(context, &thePreferences)): 
THR0tf_TF_RRR(result); 

// Stuff data into the preference dialog 

CWPanelSetltemText (context, kGutputFileEditBox, 
theFreferences,outfile); 


// ftow update the‘real* prefs data 

result = (PutThePreferences(context, &thePreferences)); 
THROW.IF ERR(result); 

1 

ca t eh {CWResuli ih \ sKrr) 

i 

result = thisErr: 

1 

// Relinquish our pointer to the prefs data 

free {outname); 
f ree( resnain^) ; 

reto rn result; 


CVPanelSetTtemText (context, kRcsFlleEditBox. 
thePreferencen.resfi1e); 


I 

catch (CWRssult thisErr) 
t 

result - thisErr; 

I 

// Relinquish our pointer to the prefs data 

if (wemHandlo) 

CWUnl ockHemllandle [context. raemHandle): If error is ignored 
return (result): 


And listing 16 shows our version of the GetData function, 
which copies data from the panel to the handle of settings data, 


listing 16: Copying settings data out of the settings panel 

GetData 

static CWResuit GetData(CWPluginContext context.) 

I 


CWResuit 
CWMemHandle 
Sample?ref 
char * 
chat * 
short 


result ” cwNoErr; 
moraHandle * NULL; 

i h eP r e f e r enc e s ; ff focal copy of preference data 
outname = (char *)malloc(255): 
resname - {char *)mailoc(255): 

i. J: 


try 

t 

// Get a pointer to the current prefs 

result ~ (GeiThePreferences(context p kthePreferenees)); 
THR0W_IF_ERR(result); 


// SiulT dialog values into the current prefs 
result * CWFanelGetltemText(context. 


I have found that non-printing character* can sometimes 
make their way into the edit-text foxes in the settings panel, so 
1 explicitly look for them and remove them from the file names 
typed by the user. 

The settings panel plug-in code contains a handful of 
other functions that save preferences on disk, restore 
preferences to their previous settings, and so forth. I’ll leave 
the inspection of those routines to the interested reader. For 
die rest of its, we can finish up by building the settings panel 
plug-in and installing it into the correct folder in the 
Code Warrior installation. 


Conclusion 

In this article, we T ve seen how to embed Macintosh 
resources into a Windows executable file, whether we want to 
develop our applications on Windows or Macintosh computers. 
This resource embedding allows us to take advantage of the 
support provided by the Quickl ime Media Layer for those parts 
of die Macintosh User Interface Tooll>ox and the Macintosh 
Operating System that rely heavily on resources, including die 
Dialog Manager, the Window Manager, the Control Manager, 
and of course the Resource Manager. This in turn makes it easy 
lo write our code once and deliver it on several platforms. 

References 

You can download the CodeWarrior piug-in SDK from 
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PROGRAMMER'S 

CHALLENGE 


by Hob Boonstra t Westford, MA 


Area 

As those of you who are regular readers know, the 
Programmer's Challenge problems have become more difficult over 
time. Just as all scientific discoveries worth making had been made 
by die mid-twentieth century, so it is that all simple Challenge 
problems have been jx>sed and solved by this time Then again, as 
they say, maybe not, “lliLs month f s piol)lcin is Ik> m y wed from 
http://www.polvmathiove.CQm/ . where Gary Smith posts software lie 
uses in teaching mathematics to elementary and middle school 
students. One of his programs is called Area Puzzles, where students 
create rectangles with specified areas to cover a grid subject to 
certain constraints. 

'I he prototype for the code you should write is: 

void Area( 

const. J^hort *cellfi* 

t rvxianglc to lx covered witli smaller revttngfcs 7 
r iiivlo (row]led] as crtbltow*rectWklth + coif 7 
r value jNX) mans U»i> cell must be cowretl by a rectangle of ana N 7 
short rectWidtb, 
short rectHeight, 

Reot yourRects[] 

): 


Your Area routine will lie called with a rectangle of cells of 
width rectWidth and height rectHeight. Your task Is to attire a set of 
smaller rectangles (yourfiect) that cover these cells. In doing .so, you 
need to satisfy some constraints. Certain of the cells will have a 
nonzero value, and those cells must lx covered by a rectangle with 
an area equal to that value. As an example, if the inpul cells were 
configured as follows ... 


0 

0 

3 

0 

t 

0 

0 

0 

0 

R 

0 

6 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

4 

0 

0 

0 

0 

0 

3 

0 

0 

1 . 

0 

0 

0 

D 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

6 

0 

0 

0 

0 

0 

0 

0 

15 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

10 

0 

0 


a 

0 

4 

0 

0 

0 

0 

0 

0 

0 

n 

0 

0 

0 

0 

u 

Q 

0 

4 

0 

o 

4 

0 

0 

3 


,,. you might create a .sei of rectangles like* this, where each cell 
is shown with tire number of the rectangle including that cell. 


1 1 12 7 2 3 3 3 3 

445222333 3 

4 4 5 6 6 6 6 7 7 ? 

4458888777 
910 10 888 8 7 7 7 
9 10 10 988 87 7 7 
9 10 10. 8 8 8 8 7 7 7 

9 10 10 8 fl 8 8 13 13 14 

9 10 10 8 8 8 8 13 13 14 

9 11 It 11 11 12 12 12 12 14 


You should return the rectangles that cover the cell array and 
satisfy the constraints as yourRects, Kach cell may lx included in only 
one rectangle, II’ die cell has a nonzero value when Area is called, it 


must lie included in a rectangle with an area equal to that value. 
Memory for the rectangles you create will lx allocated for you, and 
there will lx as many of those rectangles as there are nonzero values 
in the cells army. Any solution that covers the entire cells array and 
satisfies the constraints will lx considered correct. 

Scoring will lx based on execution time - the winner will lie 
the solution that correctly solves the puzzles with the smallest 
execution time. 

Tins will be a native PowerPC Carbon C++ Challenge, using the 
Metrowerks GxJeWarrior Pro 7.0 development environment. Please 
he certain that your axle is carbonized, as I may evaluate this 
Challenge using Mac 1 OS X. Also, when submitting you solution, 
please inc lude die projec t file and the code you used to test your 
solution. Occasionally I receive a solution that will not compile and, 
while I always fry to correct these problems, it is easier to do so if l 
have your entire project available. 

Winner of the July, 2002 Challenge 

Congratulations to Alan Hart (United Kingdom) for winning die 
July One Time Pad Challenge. Recall that this Challenge required 
readers to decrypt a sequence of messages using a "‘one time pad”. 
1 place die term in quotation marks because the pad was neither 
"one time 1 ', as it was used multiple rimes, nor was it random, as a 
true one-time pad would lx. Contestants had the advantage of 
possessing a dictionary of all the possible words in the 
aimmunicition. 

Alans solution tries each passive offset until the deccxling 
attempt results in a sequence of words found in the dictionary. The 
spued of Alan's solution Is due in part to his decision to test the 
deccxling of the first four characters of die message for each offset 
against the dictionary txfore proceeding with the resi of the 
decoding. Another factor is Alan s reuse (with acknowledgement) of 
ideas from Ernst Munters dilution to the Play Fair Challenge, 
specifically the dictionary' indexing approach. That approach creates 
ati index for cadi worel I used on the first three diameters that points 
to the first word in the dictionary Ixginning with I hose three letters, 
Pm pleased to see past Challenge axle reused successfully. 

Ernst Munters second place entry also uses a brute force 
methcxl. Ills approach is to select a possible ofistl from the pad, 
decrypt the message using that offset, verify that the decrypted 
message contains only words from the dictionary, and repeat with a 
new olfset until successful. Ernst s solution also uses a modified 
version of the SpellTree dictionary' dress he developed for the 
Playfair Challenge. 

Jonny Taylors third-place solution also examined the first three 
characters of the decoded message lo determine whether an offset 
was promising enough to continue decoding. As noted by alters, 
because the message may contain special characters not found in the 
dictionary, offsets rejected by this approach must lx revisited to skip 
potential special characters if the message is not successfully 
decoded. Moses Hall takes a different approach, creating a finite state 
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machine encoding the dictionary* Rounding out the remainder of the 
five lop-scoring entries, Jan Schotsman used the AJtivec 
programming nxxJd and repons achieving a 5% increase in speed 
over the non-vectorized version. 

The table below lists, for each of the solutions submitted, she 
number of test cases prexessed correctly, the execution time in 
seconds, the bonus awarded for axle clarity am! commentary, and 
the total score for each solution* ft also lists the programming 
language of each entry. As usual, the number in parentheses after 
the entrant's name is the total number of Challenge points earned in 
all Challenges prior to this one. 


Name 

Cases 

lime 

Bonus 

Score 

Lang 


Correct 

(secs) 




Alan Hart (39) 

20 

0.73 

25% 

5469.59 

C++ 

Ernst Munter (872) 

20 

1.30 

25% 

9721.75 

C++ 

Jonny lay lor (83) 

20 

1.67 

25% 

12499.44 

C++ 

Moses Hall 

20 

2.54 

15% 

21572.92 

c 

Jan Schotsman (16) 

20 

3-05 

5% 

28959.52 

C++ 

Tom Saxton (230) 

20 

3.08 

5% 

29268.66 

C++ 

Damien Bobilloc 

15 

12.11 

15% 

1(12918.96 

c 


Top Comisianis ... 

lisLed here are the Top Contestants for the Piognuinner's 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years, The numSx.Ts Mow include points 


awarded over tire 24 most recent contests, including points earned 
by this month's entrants. 


Rank 

Name 

Points 

Wins 

Total 



(24 mo) 

U i mol 

Points 

t. 

Munter, F.mst 

251 

8 

882 

2. 

Saxton, Tom 

65 

2 

230 

3- 

Taylor, Jonathan 

64 

2 

90 

l 

Stenger, Allen 

53 

1 

118 

5. 

WibtlxHg, Cbes 

40 

2 

49 

6. 

I lait, Alan 

34 

1 

59 

7. 

Rieken, Will eke 

22 

1 

134 

8, 

Lands! Deri, Robin 

22 

l 

22 

9. 

Gregg, Xan 

20 

1 

140 

10, 

M;i Men. Jeff 

20 

1 

Hi 

11. 

Ctx>per f Tony 

20 

1 

20 

12, 

Tmskter, Peter 

20 

t 

20 


Here is Alan’s winning One l ime Pad solution. 


One! 1 niePatLcp 
Copyright <g> 2002 
Alan Hart 

PmbkTti definition: 
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ideas out into the world. 
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Mi rocswgc \s encrypted using an unknown oflsa in the <mc time pad 

Eidi character lii Uk encrypted message is tin- sum of the aimsipufidtnf* dear text 

and pod diameters. 

Iht* sum is adjusted to remain in the vaikl character set range 

The character set is 62 uppcr/kiwer case atpfcHiuoierics 
dial appear in words in a cisednsemltive dictionary phis 33 other punctuation and 
special characters 

("delimiters") dial can appear in any locations htt w een words. 

Total time in to tie mininrad. 

Assumptions 

We cannot make any assumptions alxmt the number of delimiter characters Urn 
may p recced die message or separate Ilk’ words w ithin it.hi on ulikdy extreme case 
the message could be a sea of delimiters with a tew short w ords distributed 
anywhtrc within it. it is assumed that tile test eases will ran lie patlinkigleifaml the 
majority ot characters in die message will farm dictionary words. In parricuhr; the 
solution is optimized &>r messages with no leading delimkm before the first 
dictionary wool li decrypts merges w ith kadmg delimiters during a second scan 
of the pad 


Solution Summary: 


The external interlace calls are passed to a JXvoder class which dties I he work. 

'Ilk gEkrodcr instance is dynamically assigned by ImlOnelifltcPad O and allocates 
a fixed vc array of 236 KBytes liir the main dictionary index, further index Brandi 
records are allocated dynamically during index mg. 

Iliis adds a further iOOKBytcs to the spaa requited in die ease of the dklionry 
supplied with die test data 

The solution should Dt comfortahty in less than 500 KBytes heap space not 
including the dictionary' and message strings, 

He decoder creates a small static lookup table containing two concatenated copies 
of tilt* diameter set to aBow 6* wraparound w hen subtracting die pad and cipher 
duroaos. allowing a sinijik- lookup for decoding*and avoiding die need for range 
limiting 

iXcixiing Is done by trying each ptjssilile jxttl offset in Jum until the decode yields a 
sequence of words that arc found in the diLtkmry. 

During the firsi pass I’anelidate pad offsets are found by testing die first i diaraaere 
at cadi | nod offset with tile first i message characters, ff this tib all |«d off sets arc 
retested on the 1 whole message in esse the firsr won! dots not start at die first 
cliaraUCT of the message .Decoding with r*nth cantiubite pad is aborted if any 
invalid sequence of consecutive dietiemary characters is delected or the end of Ilk 
pad is reached. 

Lhe validity' of a character sequence is tested in tlirce surges 

1 A sequence of three or more characters must have a lieaeUY index value 

matched by one or more dictionary words , 

A shorter word must have .ui indent value that matches a hit map of 1 and 2 
character words. 

2 Characters follow ing a valid I reader index must form ^character sequences that 

exist somewhere in the* dictk xun: 

V Finally the wrmf is ctwiipared with the dictionary entries using a case insensitive 
dpraeter maieh and length re imprison 

The dictionary index uses a 32 character (5 hat) enumeration to allow quick 
calculation of compact indices, and to ctiaNe hit mapping hi a single 32 hit word. 
Hie 10 numeric characters arc enumerated using 1 to 3. with pairs of digits sharing 
The siink* index value. 6 to 31 enumerate die alplLLktk diaractersjgmmng case 
Zero is used to denote any non-dktkmary cl Lira c let, 

This cmimcr.itior means that wtjrels in die supplied dictionary containing numerals 
hi ilk; indexed duraerc-rs may not hr in correct index underdo avoid 1 laving to re¬ 
sort lik* dktkitwy this is handled in the 1 tab budding and x^irehing piocedurcs. 

This mapping and indexing system allows a quick confidence din k to hr carried 
out during decoding so dm noo-indexed final dictionary starching is only done 1 on 
longer words, anti only when iIk j wool is likely to exist. 

Words of one or two characters; arc recorded in a 32 x 32 bit map (bra last lookup* 

I lie index for a word of three or more characters is calculated by concatenating the 
index values til tile first lluve characters. 

The index selects one of an array of 32x32x32 02K) Index records used lor initio! 
and fmal validation of decoded words. 

If the Index value is die header for words longer item three diameters it lias a 
pointer to a dynamically allocated 32 entry lookup uNe. Eadl entry in file table 
points to the firsi word in the dictionary whose 4th character matches 
one character imlex value. 
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The Index record also has a hit nop of the valid fourth duracrer ifhJhx^ that can 
fidfow this sapience when it appears it character positions 5.6.9.« in the body of 
any wunl hi Uk - dkifonary. 

Optimizations applied included using unsigned types to remove compiled sign 
extend instructions, Jongs to remove compiled hyrc mask instn relit mix and the 
addition of the first pass decoder to limit the tested pad offsets to those yielding 
Yi did indices for rite first i message characters. Instruction sequencing was also 
adjusted to minimize tile time spent <m pirjcessing failed pad offsets 

AcknuwkdgtTncni 


The dictionary indexing system uses some itte gleaned by revisiting 
limst Minna's winning solution to the 1999 Playfair challenge. 


^include "OtteTlmcPsd.h" 

// use 1 unsigned types wherever possible to minimize die insertion of sign extend 
// instructions It) the compiler 

typedefunsigned char uebar; 
t ypad a f unsigned long uiong; 

typed ef unsigned long blong: // used instead of hoof to avoid diameter masking 
instructions 

static const plong IndexOffset [128] = t 
// lookup laNe to convert dnacter codes to index olfeet values 

0, 0. 0* 0* 0, 0, 0, 0, 0, 0, 0. 0* 0, 0, 0* 0* 

0. 0. 0* 0 t 0* 0, 0* 0* 0« 0, 0, 0, 0, 0* 0- 0, 

0, 0. O* O. 0, 0. 0. 0* 0* 0, 0* 0* 0. 0. 0. 0, 

l, 1, 2* 2* 3 t 3* 4. 4. 5 t 5, 0, 0* 0, 0, 0, 0* 

Op 6, 7, 8* 9, 10p lip 12» 13, 14, 15, 16, 17, 18, 19, 20, 

21, 22, 23, 24, 25. 26. 27. 28. 29. 30, 31, 0, 0, 0. 0, 0, 

0. 6. 7, B, 9, 10, 11. 12, 13. 14, 15, 16. 1/. 18. 19, 20, 

21, 22, 23, 24, 25, 26, 27, 28. 29, 30, 31. 0, 0, 0, 0. 0 

1; 


Index Value 

static inline uiong 

IndnxValue (const uchar* inWord) ( 

// Return Ehe index lik the fim Umx - cl wraeUTS of a wool 

tilung index “ TndexOffset EMinWord ++)]; 
index ” (index « 5) | IndexOffset [MinWord ++)) ; 
return (index « 5] | Ind^xOffnet I'inWordJ; 


struct Bondi 

struct Branch 1 

const uchar** fFirsttford: 
const uchar** fLastWord: 

Branch () | fFirutWord - fLastWord = NULL: I 

blong VaiidateWord (uchar' inWord, uiong inWordLengthJ ( 

// Compare inWord with each word in this bratich 

// Hr indices ;ire known to match, so in Word already' points to the 4th diameter of 
// die test wool 

// Note that the amhiguous indexing of numeric characters means it is possible to 
// return a false positive. 

// This Is not considered a problem.as we arc only trying to verify thai the one time 
// fiatl is correctly aligned to produce a string of credible words. Lkwcvcr, it means 
// liui dwttcr dfctkxary wonk ran appear williiii within tire indexed range, and 
// must be ignored 

const uchar* *wordFu ^fFIrsttford; 
do ( 

uiong header * *(uiong 1 )(*wordPtr); 

if ((header k OxOffQOOO) bb (header b OxOtfOO)} I 
// 3 nr more diameters in this dictionary word 
const uchar* wt * 'wordPtr + 4; 
uchar* w2 " inWord: 

long difference " 0; 

long leti ~ inWord Length: 

while ( ! difference bb *wl) I 
// compare the words iu nil the end of the dictionary word 
// converting upper case doracters in inWcird to lower case 
difference “ (*(wl++) - (*(w2++) | 0x20)h 
len 

) 

if (difference — 0 len *=* 0) return true: 

// words match 

if (difference > 0) return false: 

// this and subsequent words arc greater than inWord 
I 

1 while (wordPtr +h < fLastWord): 
return false: // no match lound 



class Index 

class Index 1 

// Dktkmry index entry for a Lhrer chinickT seqmnce: 

public: 

// Dam encapsulation is not used, so that ilk - decoder can access Inrfox members 
// directly hsr higher performance 

Brandi *fBrandies: 

ff Dynamically allocated list of 32 pointers to words that sun with this index 
uiong fKap: 

// Map of valid fourth character indices that can foitow this intfox in the body 
// of a word 

// iMap Iki (J is used it> registcT a valkl tJirtv letter won! for this index 

Index 0 I fBrarrches - MULL: fHap = 0: I 

-Index {) I delete [] fBranches: I 

uiong // Hcmm the numht'r of wonts rcgtstercd ftk this index value 

Register ( 

rionat uehar * 1 inWordLi ai , // Poinier to the first word to register 
u 1 on g in Index. // 1 Ihe index val l ic tor wi irds to register 

const itchar* * inLaetWord, //'Ilk - List word in the tliilionar), lor 

//range decking 

Index* inindexArray 

// lire amrv if Intfox ret:oreb. used to regrstcrworel body sequences 

) I 

// Hits is Ilk* dictionary indexing procedure 1 

// - Registers die existence of one or more 3 character words for this index in fMap 
//hit zero 

// II there are wtHds of «i or more chamderswith this index value, aJkx^tt? a 
// Brandt array and ret^nreLs tlie fit>t and Lest winds of Uk list for each ixh t h;iraaec 
// Registers the existence of each 4-letter sequence in die Ixxly of each word in the 
// (Map for its index 

const uchar** wordPtr ^ InWordList; 
uiong index = inindex: 

const uchar‘ word: 

Branch* branch * NULL: 
do I 

Uchar c - TndexOffset [M(*WOrdFtr) +3)]; 
if ic) 1 

// l or more c haracters 

If [EBrandiea NULL) { 

H uIIoguc a new branch list to index words on the 4til duniila 
fBranches = new Branch [32]; 
if (fBranches = 0) 

return 0: // imil out and signal allocation failure 

I 

// record the start and end words in each branch 

if (branch 1“ fBranches * c) t // end of previoos branch 
if (branch) 

if iqxJare the List word pointer for the old brandi 
branch->fLastWord » wordPtr - 1: 

// move to the next tirandi 
branch - fBranches + c: 
if (branchOfFirstWord = NULL) 

// rhis is the lira wore! to lie registered in dtis branch 
// insert ihe first word pointer for Uas brandi 
branch >fFirntWord ^ wordPtr: 

1 

// rcgblcr the remaining map bits for the body of this word 
word - ('wordPtr) + 3: // skip the index 
while ('word Mword+1] bb , (word+2)) I 
// while there :ire tliree or more dmracters left 
ff get the 4th ch:iracter index 

c - IndoxOffrint f Mword + 3) ]: 
if (e — 0) break: //no4thcharacKT 
ff register die 4th character in tbt* index bit map 

inlndexArrny l IndcxValue (word) 3.fMap |“ ( 1 « e); 
word += 3: 

1 

I else 

if register tile 3 dmracter word ill liit 0 of the index map 

fMap |“ I: 

wordFtt ++: // next won! 

// mull end of dictionary or imfox value changes 
I while (wordPtr < inLamWord kb 

index “ IndexValuo {'wordPtr)); 

if (branch) // updite die last liranch 
branch >fI^stWord = wordPtr - 1: 
ff return the number of wimb regisiered 

return wordPtr inWordhist; 

I 

blong ValidateWord (ucliar* inWord, uiong InWordLength) 

t 
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// The dictionary lookup procedure 
// Returns TnK 1 if the word extols in die dictionary 
if (inWordLength — 3) 

If 3 character wurd Check map hi! ti 
return [fMap & 0x01); 
else if (fBtandies) 1 

// Gimparc ihe ith and Subsequent characters with the words in die appropriate 
// branch 

Branch* * branch = fflranches + IndexOffset [*(inWord + 3)1; 
if (branch >fFirsttford) 

return branch-) ValidateWord (InWord + 4* inWord length 4); 

I 

return false; 

I 

1; 


class Decoder 1 


rfws Decoder 


private: 

fj Kid information 

const uchar' fpad: // local copy of the pad pointer 

conet unbar* FFi rstPadChar; 

// pointer to the ament first pad character 
const uchar* fLastFadChar; 

// pointer to the last pad character to try 
along [MessageLength; // lengih of the encrypted string 

// Dictionary infomation 

Index flndexArray [ 32*32*32 ]\ ft the dtedWBfy indexarray 
along fShorttforriMap 132]; 

// a bit map for one and two character wonts 
// The decoder table 

ulong fffecodeTable [I9f3]; 

if lookup iaNe to convert a pair of dpher/pad duramen to a dear character 

public 

Decoder (const uchar* inFad) 

f 

// Gmstnieiur initializes tlx* dura members 

// The dictionary irxfcx is huili separately to alknv ttnicK ft aSlocttion Muir to be 
if handled gracefully 
// initialize pad pointers anil pad offset 
fPad »inPad; 
fFirstPadChar - fPad; 

// Jill in tlx* decoder table with two concatenated copies of the character set 

int c: 

ulong* t = fDecodi Table: 

for (c - 0x20: c < Gx/f; C++, t ++) 

*t - *(t + 0x3 f) - c: 

(f Clear the slum wojd map 

for (e “ 0; c < 32; e ++) 
fShortWordMap [cl ”0; 

* 


blong TndnxDictiomiry (const uchar** inDietionary, 
along influmWords) 

I 

// Build the dictionary index and slum word map 
// Return lulse if Brandi allocation [alb 


const uchar** wordPtr 55 InDict ternary: 
const uchar** lastWord * ItiDicttonary + ItiftuuiWords: 
ulong numWords; 
do I 

// Process (he next irokx value 

along Index - *(along 1 )(*wordFtr); 
nwWards ^ 1; 

if ((index k OxOffOQGO) — 0) 
ft Register a l character word in short woixl map aero 
•fShortWardbap H (I « 

IndcxOrfstH ((index » 24) 4 Oxi'f I): 
else if ((index & OxGffGO) = 0) 

// Register a 2 dmacter word in the appropriate short wonl map 
fShortWordMapi IndexOffset[(index » 24) A Oxff] 1 
|= (1 « IndexOffset [(index » 16) 6 Oxff]); 

else ( 

// 3 or more characters 

// Pass Ujc word list to the appropriate Index reionl for registration 

index = TndexValue (‘wordPtr); 

numWorrict = flndexArray (indexi .Register (wordPtr, index. 

lastWord, flndexArray); 

if EnumWords “ 0) 

// branch list allocation Mure - hail out 

break: 

I 


ft ftcxi word list 

wordPtr +■ nunWords; 

J while (vordPrr < lasrWord); 

return {numWords ) 0); 

I 

void FindFadOffset (const uchar* InEncryptedMessago, 

uchar* oijtDec rypted Means go > along *outOffset) 
t 

// Ihe main mutine called to decode messages 

// Use trial and error to find a pad offset that successfully decodes the mcssige 
// Return the offset found in ‘outOffset 


ii Ftrai Piss 

// Optimized search fur candidate pad offsets that decode a valid word index at the 
// firsi encrypted character 

// Build l<H)kup Mies to decode each of the first i message characters to its index 
// value liir any pad character 

// Shift the pad thmugh a 4 character buffer and apply tliis u> die i message 
ft characters 

typedef uloag PadMap [12B|; 

along cO. cl. c2: 

ulong* ntapPtr; 

const uchar* pad; 
blong validOffsct; 

ulong map. i: 

const uchar* cipher = inEncryptedMessage: 

PadMap padMapArray [4]; 

// Measure* tile encrypted message k-nglh 

while (*(++cipher)) E;l 

FftessageLength “ cipher InRncryptedHessage: 


cipher w inEtictyptedHessage: 

for (map “ 0; map < 4: map ++, cipher H) ( 

if orttc iIk* dtxxHk* table for die next cipher character 

mapFtr = padMapArray [mapl; 

// dear tin entries for invalid pud dumrirrs 

*(raapPtr + 0x7f) w fl: 

i “ 0x20; while [l ) I *(twpFtr++) = 0; | 

ft m the ikx'ixlul index vote fortueh valid pad dwtacter 
// calculate tlx first irffset in the decode Labk for this cipher character 

ulong* c ■ fffecodeTabie + 0x3f + 'cipher; 
i = QxSt; while (i -*) ( *{raapPtrH) ^ T 

ndpxOffset [*(c }]; 1 


1 


// Start at die beginning of ihe one lintr pad. 

// Decode tlicse i clwrancrs with each jxid offset aivd lixik fur a valid word or index 


fFlrstPadChar ^ IPad; 
validOffset = false: 
pad = fPad: 

// prime a scquciKf of i diameters with (Ih j first 3 valid pail eharaiters 

ulong padBuffer = €; 
for (1 = 0; i < 3: 1 ++) E 

while ('pad < (1x20 11 ‘pad > Ox/e) I 

i f ('pad “ 0) r el urn: ft Alxal if ihe jxxl is k*ss than 4 eiiaraeters 

pad ++: 

J 

padBuffer & (padBuffer 8) | *(pad H); 

1 

do E 

ft Shill die next valid p;ul character into the sei 

while (*pad ( 0x20 || ‘pad > Ox/e) I pad ++; 1 
padBuffer w (padhufler &] | ‘(pad ++); 

if ( tcQ = padMapArrayiEJj [padBuffer » 24]) ) 1 

ft 1 st chiractiT iket xics to a dk tii man character 

if ( (el - padHapArrayll] [ipadBuffer » 16) & Oxff] ) ) 1 
// 2nd character decodes to a dk tionary duuweter 

if ( (c2 “ padMapArray [2] [(padRuIf-cr » 8} & Oxff]) ) I 
// select tlx* appropriate lnik*x revotd for die 3 clxraeters 

Index* header =fii»dexArray + ((((cO « 5) | cl) « 5) | 

t2); 

// delink tlx* ith duracUT 

if ( (cO “ padMapArray [3] [padluffro ^ Oxff]) ) 
ft check titai die Brandt index exists for the ith. character 

validOffset = header - >fBranchQS 

bcadur )fBranches |e0] , 1’FirstWord; 

else 

// check fix* a valid 3 character wool 

validOffset - header->fKap & 0x01; 

) 
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// check fur a valid 2 diameter wood 

validGffset - fShortWordMap [cOj b (] << cl); 
I else 

// check fur a valid single character won I 

vaiidOffset = ('fKHortWordHap) b (X « cO): 


uchar* outDecryptadHcRsagc) 

1 

// Galled b\ FimlhidOffself ) wkh UlrbiTadQiar pointing u> the sum uf a caixJkliic 
// pad 

// Attempt to decode die message using this pad and return sutvess/ikilure 


if (validOffeOt} [ 

// This jm\ offset decodes a valid word or index 

// ay to decode the w hole message using this candidate pad 

validOffset = ApplyPad (inEncryptedMessage, 
outDecryptedMensagc): 

\ 

1 

// move die pad offset to tlx- next valid pad character 

do | 

if (* (filratPtidChar + fHes sageLength)) 

FBlrsiFadChar ++: 

else 

// Wo ve run out of pad dntaden - end of psiss I 

goto SeeondPass; 

1 while £*fFirntPadChat < 0x20 || 'fFirstPadChar > 0x7o): 


const uchar* pad; // pointer to the cumin pad dtracter 

cons t ucha r * cl phe r; // pointer to tlx next encrypted character to decode 

uchar * c 1 ca r; // pointer to die next clear character lo decode 

u 1 on g index: // ii idex value of current word 

const along* origin “ fBecodeTablc + 0x51; 

// pointer lu dfcc origin in die llecodeTahle 
uchar * word: // pointer to start of nm-nt wool Ixing jttoeessed 

Index 'body, *headn r; // pointers to the Index records for the 
// cunvnt word 

tilong e€« cl* c2; 

// index values of tlx fust tluec diameters of teh aimmi word 
ulong state ""0; // controls progress of ttv word decode process 

clear = outDecryptedMeasage: 
cipher - inEncryptedMeBssgje; 
pad “ TFirstPadChar; 


] while ( ! va 1idOffset); 


If { l validOffset ) f 


SocondFass: 

// Second Pass 


// Tltc search lor the first index may have failed due to kradtiig delimiters 
// fry to decode the message using every pad offset in turn 

fFirstPadGhar ” fPad: 
do 1 

validOffset - ApplyPad (inEncryptedMcssnge* 
outheeryptedMossagc): 

fFirstPadChar H; 

I while C ! valldOffcot && '{fFirstFadChar * 

fMessageLength)); 


1 

// return the ofisii 

’outOffset * fFirstPadChar fPad - 1; 


I 


blong ApplyPad (const uchar* iriEncrypt ^Message, 


do t 

// ft if each character in the mevMigtr 

// next valid pad character 

while {'pad < 0x20 || 'pad > 0x7o) I 
if ('pad) pad++; 
else goto Exit; // end of pad 

\ 

ff decode the character 

’clear 1=7 ’(origin + 'cipher ’pad); 
switch (state) I 

case 0: // to Miking h ft I st character of a word 

if ( (cO - IndcxOffset I'clear]) ) 1 
word = clear; If I st diameter of a word 
state * 1: 

I 

break; 

ease l: // bn king fi *r 2nd dmeter i if a word 

if ( [cl - IndexQffset ['clear]} ) state = 2; 
// 2nd dictionary char 
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else if ((*fShortWordMap) & Cl « cO)) 

// VaUd 1 d LlHK lLT wtird 

ntate " 0; 
else goto Exit; 
brfiak: 

easy 7; // tanking for 3nJ character of a word 

If ( Cc2 “ IndexOffset [’clear]} ) I 

header -f lrsdexArray + (C((e0 « 5) | ci) « 5) | c2); 
state = 3: // 3rd dictionary char 
) else if (f Short VtardMap |c0] h U « cl)J 
// v;ilid 1 dy racier wml 
state “ D; 
else goto Exit: 
break; 

case 3: // It Hiking tar 4ch diameter of a won! 

if ( CcO “ IndexOffset 1‘clesr]) ) I 
If (header >fBranchcs bb 

header->iBrancbes IcOj T fFirstWord) [ 
i ri d ex ” cO: // valid 4th dictionary char 
body - NULL; 

state = h ; // check bodysequeoces 
\ else goto Exit: 

I else if (headerOfWap & 0x01) 

U valid 3 character word 
state “ 0; 
else goto Exit; 
break; 
c a se 4 1 

if ( (cO = ItidexOffset [‘clear]) ) [ 
if (body “ NULL) [ 

: t s - [index << >. | cO; // arcumidaic rhe body irxinc 
if (index > 1024) 

// third hod) index dwactcrsdeci ilic Index record 
body -= tlndexArray + index; 
else ! ft tank up this character in the current body Index iccocd 
iT (body >fHsp b (1 << c0)) I 
// valid sequence - start bidding the next IxkJv index 
Index “ cO: 
body - NULL: 

| else goto Exit; 

1 

I else [ 

// end of ilk 1 wfttti, confirm it is in the rBetiottury 

if (header->ValidateWord (word, clear - word)) 
state * 0; 
else goto Exit: 

default; 
break; 

I 

pad ++: 

dear ++; 

I while (M-H-cipher)): 

Exit: 

* clear = 0;// terminals the decoded string 

return ((‘cipher) 0); // snoocsdiil if we readied the 1 rod of the 
// message 


* gDecod e r; // global pointer to a dynamically Li31ocjtc.il instance 



OpenBase SQL 

High-Performance Relational Database 



The Database That 
Pays you Cash 

Announcing unlimited single-user 
runtimes for just $ 350 o year. 


InitOneTbncPad 

void IniLOtieTiuiePad (const char ‘oneTimePad. const char 
’dictionary[], Long numDictionaryWorda) I 
// Create the dernier 

^Decoder = new Decoder ((const achat 1 *) oneTimeFad): 
if t ^Decoder) I 

// Index the dictionary 

if f ] gDecodet’>IndexMctionary ((const uchar“) 
dictionary. 

Culong) nuinDictionaryVoirds)) f 

// Allocation Mutt 

delete gDecoder; 
gDecoder = MILL; 

) 

1 

] 


rXxaypcMcwjge 

void DecryptNessage(const char 'eiicryptedM&ssage. char 
• dec ryptedto sage, long ‘offset) I 
if (gDeeoder) 

gDecoder->FindPadOffset [(uchar■) encryptedHessage * 

(uchai*} decrypt edMessage, (ulong*)offseL); 


void TermOneTimeFad(void) 
delete gDecoder: 


TmnOntTbnePad 
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Table Techniques Taught Tastefully (part 2) 


Using NSTableView for Real-World 
Applications 

Introduction 

Pan one of this series of articles introduced the wonderful 
NSTableView class in Cocoa, going over the basics—displaying 
textual data, adding and deleting rows, and adjusting the 
columns of a table. With those techniques, you should be able 
to write code with some pretty useful displays. Bui there's so 
much more you can do with NSTableView, and this part of the 
series goes into some intermediate techniques that will help you 
feel like a 'Table Jockey.” 

In this article, well cover a liLLle biL more in the topic of 
deleting rows that we introduced in part 1. Then we'll 
introduce alphabetic type-ahead, which allows the user to start 
typing ilie first few letters of a row's relevant text to get the 
selection established. Next, well cover several aspects of 
sorting and reordering a table’s rows, including sorting by 
clicking on a column header and drag-and-drop rearrangement, 
Finally, well cover exporting of data from a table via drag-and- 
drop and via the clipboard. 

Be sure to follow along with the “TableTester" application 
(downloadable at www,karefia.com/tabletester/), a program 
showing off most of the table features described in this series. 
It contains the source code corresponding to the techniques in 
this article as well as those in part one, in case you missed ii the 
first time around. 

Deleting Rows (The Sequel) 

In part I, we discussed how to delete the selected rows in 
a table, responding to a button or the Clear menu. How about 
deleting the selected rows when the delete key is pressed? This 
requires us to create a new subclass of NSTableView and 
override the key Down: method to pass along the same 
deleteSelectedRowsInTableView: method to the data source. To 
create the user interface for this, we create a table but then set 


its custom class to our sulxlass, DcletableTableView, using the 
class inspector in Interface Builder, 

Listing 1: DeletableTableView.nl 

ktyUowti: 

imp out deleter keys mid pass along the method to delete Lhe selected rows. 

Otherw ise, just let the superclass handle the event. Tire table must be "first responder* 
for this ro be processed. 

(void) key Down: (NSEvent 1 ) the Event. 

f 

KSString "keyString 

“ [theEvent eharnctersIgnoringHodifiernl ; 
unichar keyChar = [keyString characterAtIndex:Ol: 

switch (kcyChar) 

[ 

case 01//: // Delete Key 
case NSDeleteFunctionKey: 
case NSDeleteCharFunctionKey: 

if ( [self selectedRowl >= 0 && [(self dataSource] 
re s po nd sToSelerto r : 

Rett lector(deleteSelRctedRowsTnTahleViev:)]) 
l [self datttSource] 

deleteSelectedRowsInTableView:self]; 

I 

break: 

default: 

[super keyDown:theEvent]; 

I 

I 


A feature not implemented above is undoahility; well leave 
this as an exercise for the reader. 


Alphabetic Type-ahead for table selection 

When lists are long, keyboard navigation — the ability to 
start typing on the keyboard to navigate to the desired 
elements in a list — is quite convenient. This functionality 
isn I built into NSTableView, but ii is possible by creating a 
subclass that pays attention to the keystrokes when the table 
is active. 

Tile algorithm is fairly straightforward. When the user 
presses a key. the key is appended to a string, and that string is 
used to try to select the closest row in the table. As more keys 


Dan Wood once took an introductory Arabic class, but nobody in the room knew what language they were being taught. He likes to buy fruits and 
vegetables Ifom the farmer's market on Tuesday mornings. He missed the last two days of WWDC this year due to the birth of his son. He is the author 
of Watson, an application written in Cocoa. Dan thanks Chuck Pistil a at Apple for his technical help with this series, and acknowledges online code 
fragments from John C Randolph, Stephane Sudre, Ondra Cada, Vince DeMarco, Harry Emmanuel, and others. You can reach him at dwood@karelia.com. 
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are pressed, the string builds up, and the selection Incomes more 
refined, If a time interval of a couple of seconds passes with no 
keystrokes, the typing buffer is cleared, so the user can make a 
fresh selection. 

To handle the keystrokes, we override keyDown: to merely 
send rhe interpretKeyEvents; message to self. According to the 
NSEesponder documentation, this is how to intercept 
keystrokes; it will cause the insortText: method to lie invoked, 
which we handle hdow. 

Listing 2 : TypeahcadTableVtew.m 


keyDown: 

Indicate that the keystmkes from the event should he interpreted. The table needs to 
be "lirhi responder* for this to he effective. 

■ (void) key Down: (NSK vc ti L *) i uEvent 

f 

(self interpreiKeyEvents: 

[NSArray arrayWlthQbject:inEvent]1: 

t 

We then implement insertText: to add the typed characters 
to our buffer of keystrokes, and go select the appropriate row 
based on what has been typed so lar Thinking in terms of 
Model-View-Cc>ntroller partitioning. we send a n lessage fr<mi the 
view (the NSTableView subclass) to the Controller (the table’s 
delegate) to perform the selection, by invoking typeAheadString: 
inTableView: on the delegate. We will provide a sample 
implementation later. 

We also queue up a message to send in the near future to 
clear out the keystroke buffer But what is the magic number 
for the time delay before the buffer is cleared? You could hard¬ 
wire a constant, but that might not satisfy all users. Instead, 
you can base the time delay on the “Delay Umil Repeat** setting 
in the System Preferences, The chapter from Inside Macintosh 
(Remember Inside Macintosh?) on the List Manager 
recommended two times that threshold value, but no more 
than two seconds. Whereas Carbon programs get the delay 
from the low memory global function LMGetKeyThreshj). this 
value is available via the defaults mechanism via the 
" I nitia 1 Key Repeat" key. 

Listing TypeaheadTableView.nl 

mscftTcxt 

Process tht 1 lexi by adding it to the typeatatl buffer and selecting the appropriate row 

- (void)insertText:(id)inString 
1 

// Make sure delegate will handle typrahead message 

if ([[self delegate] rcepondsToSelector: 

e1ec to t (type Ahe a d S Uing;inTa bleVie v;)]) 

I 

//We dear it out after two times tlie key repeat tale 'InitialKcy Repeal* n«*r 
// default (converted from sixtieths of U second to seconds), hut no more Hum 
two 

// seconds..This behavior is determined based on Inside Macintosh 
documentation 

// on tile List Manager. 

SSOserDefaults 'defaults 

* [NSURerDefauUs stsndardUserDefaultsh 
Int keyThregtiTiehs 


- [defaults integ€rForKey:§ B TnitialKcyEcpeat"]: 

NSTi me Int e r va 1 c I e a rDe lay 

= MirJ(Z.0/6O.O*keyThreshTicks, 2*G): 

if ( nil = uStringToFfnd ) 
t 

ntStr IngToFind * [ iNSMutableString alloc] init]: 

// hmh allocate the mutable string if needed 

1 

[tiStringTqFind appendString:inString]: 

// Qmcd any previously queued future invocations 

[MSObjoct cancel Prev I ousPerfortriRequestsWithTarget: self 
seise to r: ftscl oc t O r {c lea r Ac c umu iatingType ahead) 
object:nil!: 

//queue an invoc.it ion of dearAccumutatingTypeahead lor the near future 

[self perfonnSelectort 

elector(clearAccmnulatingTypeahead) 
withObject :rrll sftnrDel ay: clea r Delay ]; 

// Let the table's delegate do something with tile siring 

//We use stringWirh String to make an tuUHdeasvd copy for its use, 

// since we may clear out the original string bdow before it can be used, 

[Uelf delegate] typeAheadString: 

iNSSt ring stringWithString:roStrtngToFind] 
inTableView:self]; 

1 

) 


dearAcaimulatinigTypeahcad: 

Clear out the string so our next lypobead will start from scratch. 

(void) clea rAc cumu lat i ngTypeahead 
I 

niSt ri ngToFind hp tSt i i ng: ]; II dear our the queued string to find 

I 

flend 

All that remains now is rhe nitty-gritty of finding the 
appropriate mw to select based on the siring the user has typed 
so far. Usually, this will mean finding a row that is a close 
match, not necessarily an exact match, to the search string. In a 
list of US. States, for example, *M" would select Maine; “MP 
would select Michigan; “MIS n and "MISS" would select 
Mississippi; “MISSO* would select Missouri, 

In our TableTester code, we select based upon 
whichever is the currently sorted column. We search linearly 
(ideally, ii should be a binary search if the data set is large) 
for the row containing the dictionary with the value of the 
current sorting key that is a best match, using a case 
insensitive comparison* We use the Iasi row if no match was 
found, e.g. if the user typed in a table with no K Z" entries. 
That row is selected and the table view scrolled to make that 
selection visible* 

Listing 4: SortiQgDelegate.ui 


type A headSi ring: iiffibteView: 

Actually sdtn the appropriate mw based upon the string that has been typed. 

(void) typeAheadString: (NSString ')inString 
inTableView: (NSTableView MinTaMeVUw 
I 

NS Table Column - [ I nTnbleView highlighiedTableColumil : 

if (nit !- col) 

I 

NSSt ring *key - icol identifier]: 

ItlL i; 
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for f i ■ 0 ; i { [oData count] ; i++ ) 

t 

NSDIctionary *ro*BicT = [oData objectAtIndex:J]; 

RSSttitig 'corapareTa = [cowLHct objectForKey:key] : 

NSComparisonResuit order 

= [inString caSfilnsensitiveComparercoBpar&To]; 
if (order !* NSOrderedDescending) 

I 

breaki 
I 

J 

// Make sure wetc nor overflowing the row count, 

if (i >- [oData count]) 

( 

i ■“ [oData count] - 1; 

I 

// Now select row i — either the one we found, or Lite list row if not found, 

[inTableVlev selectRowii byExtendingSeleetlomNO]: 

[inTableVIow sc roliRowToVisib1 r?: i ]; 

I 

I 

One final note on ty pea head: Code Warrior has a nice 
feature of showing you the typeahead buffer so you can see 
w h a t yon I la v c ty j >ed. I n die Ta I) I eTester \ m >gram, bul n< »t 1 isicd 
here, are some minor additions to the TypeaheadTableView 
class that will display ihe current ty pea head buffer if you have 
hooked up a text field to die appropriate outlet. 

Displaying Mohl Than Just Strings 

Usually, a table cell displays a piece of plain text, just an 
NSSuing returned in tableView: objectValueForTableCofumn: row: 
But this method is designed to return “id 1 , meaning any object. 
Without any extra effort, you can return an NSAttributedString 
or NSNumber instead of an NSSlring, And with just a little bit 
of setup, you can display other kinds of cells such as images 
and buttons. 

First, you need to set the table’s columns to use a different 
cel] type. In a convenient initialization method, such as your 
controller's awakeFromNib method, just allocate a new cell 
object, such as an NSButionCell or an NSlmageCell You may 
need to adjust attributes of your cell (for instance, setting a 
button cells type and image position). Then, find the 
NSTahleColumn object corresponding to the column to affect, 
and replace the default text cell with your newly allocated 
instance, using setDataCell:. (Alternately, you can create a 
disembodied control in your nib file that represents the 
prototype cell and hook it all up in IBO 

In ourTableTester program, we allocate a button cell and 
an image cell. The button cell i,s set up to be a checkbox 
(NSSwitchButton); the image cell doesn't need any 
adjustment. Finally, the button and image cells are hooked 
up to the columns. 

Listing 5: CellDelegate.in 


awakdrumNib 

Set the tabic columns lo use button and image cells mther than the default text cells. 

- (voidJavakeFromNib 
t 

//Allocate the cells 
NSHulrto nCe 11 * bu 11 on C e 11 

- [ [ [NSButtonCell alloc] lull] autorelease]; 


NSImgeCeii ‘imageCell 

= [1fNSIma&eCell alloc] init] autorelease]: 

// Find the columns 

NSTa b 1 eCo 1 unm * b u U o tiCo Iujdil 

- [oTable tableColuiEmWithidentifieu^"checked 11 j: 
NSTab 1 e Coluurn 1 image Colunm. 

=* joTable tableColtinaWithldentifier^"icon"] : 

// Set up die button cell and mstafl into the column 

[buttonCell aetButtonType:NSSwitchButton]: 
[biirtonCell setTmagePpsitioTiiNSTnageOiily] : 
[butLOhCell setTitle:#" 1 ']: 

[buttonColunm setDataCell:buttonCell] : 

// lasud) ihe image cel! 

[imageColumn setDataCell;imageCell] : 


To display these non-textual cells, you need to provide 
appropriate data in tableView: objectValueForTableColumn: row: 
and perhaps also make per-cell adjustments in tableView: 
willDisplayCelt: forTableColumn: row:. In TableTester, we 
implement the data source and provide an appropriate object 
based on the given column. For the “icon" column, we 
provide an NSJmage object based on the name in the data 
table. (This relies on their being an image available for the 
name: we have a few sample images created with Stick 
Software's “Aquatint" program bundled with Table Fester.) For 
the “checked 1 * column, we provide an NSNumber object 
corresponding to the state of the checkbox. For the “name" 
column, we build up an attributed string to display in the 
default string cell. (And in the source code for TabieTester, 
not shown here, we also have a cell for a “relevance* control, 
which uses a custom cell class.) 


Listing 6: CellSotirce.m 

table View: objectVahieFurTahleColumn: row: 
Provide tht data for a given cell We provide different data depending on which 
column is passed in as a parameter 

(id)tableView:(NSrableView *]inTableView 

objectYalueForTableColuran;(NSTableColumn *)inTableColumn 
row:(int]InRowIndex 

\ 

id result = nil: 

// Start out with the siring that the SimpteSource returns from the dictionary 

id stringValue = [super rubleView:tnTsbleVfev 

objectViOUuForTiibjeColuJiinr inTableColUBiti tow: tnRowTndex]: 

// Now, handle special cases depending tin the La hie column identifier 
NSStrlng 'identifier - [inTableColumn idemifierj: 
if ([Identifier isEquaIToString:@ l, icon w ]) 

t 

if (nil t= strlngValue) 

t 

result _ [NSlmage imageNamed: string Value] : 

I 

1 

else if ([identifier isIgualToString:@"ches^®<i ,t 3) 

I 

// Return NSNumber of I or l). The line below builds the NSNumber 
// from from the string or NSNumber currently in the dictionary 

result - [ MSN u tuber numberWi Lhltil: [sLtingValue intValuell I 

] 

else if ([identifier isEqualToString:9"name"]) 

I 

// Really, these dictionaries should be created once and cached. 

NSDictionary 'plainAttr 

= [NSDictionary dictionaryWitbObject: 

[NSFont cystemFonrOfSIze:[NSFont systomFontSizR !] 
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forKey :KSFom/Vt tributeName] ; 

NSDlctioimry ‘boldAUr 

= [NSDicti&nary dietianaryWiihQbject: 

[NSFont boldSy£teniFontQfSiz&: [NSFotii systemFcmtSize] ] 
forKey:NSFontAttributeNaine]: 

// Return an attributed string, with the first character boldface. 

result - [[[NSKutableAttributedSiring alloc] initj 
autorelease]; 

[result appendAttrlbutedString: 

[[[NSAttrIbutedStriug alioej 
InitHithString: [strittgValtie substringtolndex:I) 
attributes :bold At. t r] autoreleaEeJ J i 
[result appsndAttributedString: 

[([WSAttributedString aliocl 

inltWILhSUing: Lstrin&Value substringFromTndex:1] 
a 1 1 rlbu Les:plaiuAtt rj autorelease]|: 

) 

else 

l 

// If mu ihe special cases, we've go lien the string result from the superclass. 

result = stringValue; 

I 

return result; 

) 


Sorting Tables 

Displaying a table with its data sorted can enhance 
readability greatly. What's even mure useful is if you give 
the user die ability to decide which column to sori a table by, 
and which direction to sort in. Astute readers will remember 
an article by Andrew Stone that covered sorting of tables in 
the August 2002 issue of MacTedi; this sen inn rakes a 
slightly different approach (and offers Mac OS X 10.2 
compatibility too). 

To support column sorting, you need to implement 
tableView: dtdClickTableColumn: in your delegate. Your code 
would sort the data and redisplay it, highlighting the clicked 
column to provide feedback to the user as to what column the 
data is sorted by. If the user clicks on the sorted column a 
second time, the direction of the sort should change, and a small 
graphic in the column should indicate whether the table is 
sorted ascending or descending. For this to happen, you need 
to implement a bit of axle. 

First, let's deal with the actual sorting, NSArray anti 
NSMutableArray provide a number of methods for sorting. The 
most convenient methods you can use are the methods 
sortIJsingFunction; (if you have an NSMutableArray) or 
sortedArrayUsingFunction; (if you have an immutable NSArray). 
With these methods, you provide a C function that knows how 
to compare two objects and is given an arbitrary context for 
performing the son. In our sample case, we use a simple 
structure specifying Lite key to sort upon, and the direction to 
sort in. Our function, ORDER BY_CONTEXT, sets up the order 
for the comparison based upon the sorting direction, and then 
invokes either easel nsensitiveCompare: or compare: Ixriween the 
iwo objects. The former is useful for strings; the latter is useful 
for numbers or dates. Our method sortData invokes 
sortUsingFunction: on the data array using the current seining key 


and direction, then causes the table to redisplay itself with the 
reloadData method. 

Listing 7: Sortingl>elegatc.m 


ORDER_RY„CONTEXT 

C function to return rhe son oak-ring for die given two objects .md the given context, 

rypedef struct I NSString # key: BOOL descending; ) 

SactContexT: 

int QRDER.BY CONTEXT (id left. Id right, void ’ctxt) 

I 

SortContexl ’context w (SortContext*)Ctxt; 
int order * 0; 

Id key = cant ext->key; 
if (0 !■ key) 

l 

id first. second; // the aaml objects to compare 

if (context-^descending) 

I 

first ” [right objecxForKey;ksy): 
second _ [left objectForKey:key]; 

) 

else 

f 

first ~ Ileft objectFarKey;key] ; 
second — fright objeetForKeyikey] ; 


tf ([first respondsToSelector: 

^selector{caselnsensitiveCompgre;)]) 

I 

order * [first caseTnsensit LvoCoitipare; second]; 

1 

else J! sort numbers or dates 

I 

order - [(NSNumber first compare;second); 

l 

I 

return order; 
f 


sortData 

Sort ifre data army based on the current sorting key (column) and sorting direction. 

- (void) EortfJflta 
I 

SortContext ctxt=l mSortingKey. aiSortDencend Ing I; 

[oData sortUsingFunction:ORDER BY CONTEXT context:fcctxtj: 
[oTable reloadData]; 

I 

Since we warn to indicate the direction of sorting, we display 
a little triangle in the table column using the -[MSTableView 
setindicatorlmage; inTableColumn:) method, in Mac OS X 10.2 t 
Apple provides official access to these images. But if you want 
your sorting-table application to work under 10.1, you have a 
couple of options. One is to include the images in your 
application’s executable; another is to carefully make use of a 
private (undocumented) methtxl in NS'I able View. Using private 
methods is something you have to be very careful about, because 
Apple doesn't support them, and they could go away at any time. 
To make sure that the sample code will work on both 10.1 and 
10 ,2 t we test for compatibility using mspondsToSelector: to fail 
gracefully, then add class methods to NSTableView called 
ascendingSortlndicator and descendingSortlndicator to safely return 
the images well need. 
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Listing 8: NSTableView+utiLm 


asccndinH^mtlndiottor 

Safely return the ascending sort tri;mglc iirupt; works on both 10, l and 10,2. 

+ £NSImage *) ascendingSortlndicator 

i 

NS image *result 

~ (NSlmage imageNaraed:@ rt N5Ascending$ortIndicator"J; 

If (nil ^ result 

t th [(NSTsbleView class] respondsToSeleetor: 

©selectorLdefaultTableHeaderSortimage) 1) 

( 

result = [N$Table?lev defaultTableHeaderSortlmagi?); 

I 

return result: 


descend! ngSortTndirjtor 

Safely return the descending sort triangle image; works on both 10.1 and 10.2. 

+ (NSImage *) descendingSortTndlcator 

\ 

NSIraage 'result 

= (NSImage imageNaraed;©"NSDescendingSortIndicator"]; 
if (nil = result 

&& | [NSTab]nVlew class] respondsToSelector: 

©selector(_de faultTableHead erReverseSortImageJ]) 

I 

result 

• [NSTabieView defaultTsbleHeaderReverseSortliaage]: 

I 

return result: 
l 

Now to specify how clicking on a column sorts by that 
column. If it's a dick on an already selected column, we reverse 
the .sorting direction, Our method sortByColumn: is fairly 
straightforward; given a table column, we switch son order if it f s 
a dick on the previously saved column; otherwise we change to 
a new sorting column. We invoke the column sorting method in 
the delegate method tableView: didClickTableCoiumn: to respond 
to column dicks. In a full application, you may want to store a 
preference of the sorted column and initially sore appropriately, 
perhaps calling sortByColumn; in your awakeFromNib method. 

Listing 9: SortingDeiegate.m 

son fly Column: 

Sort die cable by the given column, changing win dtrceikm if already sorted by that 
column, 

- (vnld)sortEyColumn:{NSTfibleColumn *)JnTableColumn 

if (raSortingColumn = inTableColumn) 

( 

//User dicked same column, change sort order 
inScrt Descending = SmSortDescending: 

1 

else 

t 

// User clicked new column, change okl/new column headers, 

// save new sorting column, and re-sort the array. 

mSortDescendlng * NO; 
if (nil 1= mSortingColuran) 

I 

[oTable setindlcatorrmag 0 :uil 
inTableColuiui: laSo rtingColumn]; 

(self setSortlngKny:[inTabi©Column Identifier]1; 

[self setSortingColmmninTableCoIutimj : 

[oTable s at High 11 &h t edTab 1 eCo 1 u ran: iuTableGo lumn 1 : 


[oTable setlndicatorlmage: (inSort Descending 

? [NSTabieView deseendingSortIndicator) 
: LNSTabieView asceiidingSort Indicator] ) 
inTableColumn: inTableColunrnl: 

//Actually sort the data 
(self sortData]; 


table Vie w: didOrkTablcCol umtl: 

User clicked on a ruble column, so sort (or invert die sort) by that column 

(void) tableView: (NSTableView'HhTablaView 

didClickTableColuran:(NbTableColumn * JInTableColuam 

I 

[self sortByCollimn:inTableColumti]: 

I 


Maintaining Selection for a Sort 

In the above example, one potential problem is what will 
happen if any rows are selected when you sort Lite table. The 
selected row's will remain the same positionally, but the items 
selected will no longer he the same. You could dear out any 
selection when you sort, but it's more useful to maintain the 
selected items though a sort. The method 

saveSeleetion From Table: gathers up the array items into art NSSet, 
and restoreSelection: toTabie: finds those items after ihe array has 
been sorted and reselects them. These methods should handle 
simple cases, though the selection restoration code may not 
perform well for large arrays since -[NSArray 
indexOfObjeettdenticaJTo;] is essentially a linear search. 

Listing 10: 8ortingDdegatc.ni 


saveSdectk mFromTa hie 

Create a set that represents the current selection from a table, for later rtstotal 

(NSSet *} saveSelccllonFromTable:(NSTabieView *)inTableViev 

1 

NSMutableSei 'result = [NSMutableSot set]: 

NSEnumerator ‘iheEnum 

- [luTableView selecterfRnwKnuineratori: 

NSNumber ‘rowNum: 

while (nil 1“ (rowNura - [theEnum nextObjetrt]) ] 

1 

id item ” [oBata object At Index: [rowNum intValua] 1; 

Iresult addObjeCt:item|; 

J 

return result; 


rcstoncSdection: to! able 

Restore die selection from the given set of row objects after a uhlc has been sorted 

- (void) restoreSelectidn: (NSSet *)in£eIectcdlLefliNums 
toTable;(NSTabieView •)lnTableView 
I 

NSEn ume r a to r 6 1 heEn ura 

“■ [inSelectodltemNums objectEnumetaLorj ; 

Id item: 

int nsvcdLastRow; 

(inTableView deseleetAllinilj: 
while (nil != (Ite® - ItheEnum nextObjeetl) ) 
int row — [oData indexOf0bjpctTdGi!LicaiTo;itera]; 


72 


Table Techniqit-s Talio!U Tasthfuuy (pakt 2) 


Ma<Tech • OCTOBER 2002 









Visual QuickStart 
Get up and running 



HTML for the World Wide 
Web, Fifth Edition, with 
XHTML and CSS: Visual 
QuickStart Guide 

Elizabeth Castro 
0-32M3007-3 - $2139 


The Web is changing how it does business and so 
should you! If you're still coding like it was 1999, you 
need to update your HTML skills with Elizabeth 
Castro's HTML for the World Wide Web , Fifth Edition, 
with XHTML and CSS: Visual QuickStart Guide. This 
latest edition of the original book on HTML wilf have 
you creating complex, dynamic sites that look good 
across all browsers and platforms—including hand¬ 
held devices and cell phones—in no time! 



PHOTOSHOP 


m WINDOWS * MAOWOW 



Photoshop 7 for Windows 
and Macintosh: Visual 
QuickStart Guide 

Elaine Wetnmann and 
Peter Lourekas 
0-201-88284-1 * $24.99 
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Mac 05 X 10.2: Visual 
QuickStart Guide 
Maria tanger 
0-32M5801-&. $2139 




iPhoto 1.1 for Mac OS X: 
Visual QuickStart Guide 
Adam Engst 
0-321 12165-1 * $ 19.99 


Final Cut Pro 3 for 
Macintosh: Visual 
Quick Pro Guide 
Lisa Brenneis 
D-321-115B3-X * $29.99 



DREAMWEAVER 

FOft WINDOWS A MACINTOSH 



rVtHUViui, KUiXb 


Macromedia Dreamweaver MX 
for Windows and Macintosh: 
Visual QuickStart Guide 

J. Tarin Towers 
0 201'84445-1 *$24,99 


© 

\0 » N(GI|HQ 
mil SMITH 


JavaScript 



JavaScript for the World 
Wide Web, 4th Edition: 
Visual QuickStart Guide 
Tom Negri no and 
Dori Smith 

0 - 201 - 73517-2 * $ 19.99 



Macromedia Flash MX for 
Windows and Macintosh: 
Visual QuickStart Guide 
Katherine Ulrich 
0-201-79481-0 • $24.99 



Macromedia Flash MX Advanced 
for Windows and Macintosh: 
Visual Quick Pro Guide 

Russell Chun 

0-201 -75846-6 * $2939 
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// look for an exact match, which is OK here. 

if (NSNotFound != cow) 

1 

[inTableViev selectRow:row byF.xrendittgSelection: YES] : 
savedLastRow “ row; 

J 

1 

(inlableViev £croHR gwToV isibie;savedLastRowl; 

} 

To make use of these selection methods, we just save die 
selection Itefore sorting and restore it afterwards. Tliis is the 
new implementation of sortData from above* * 

Listing 11: Sorting Delegate .m 


snrtData 

Son the dau. but this time, saw the sdcctfon before the sort anil restore it afterwards, 

* (void) sortData 
I 

SortCcmiext ctxt={ mSortingKey* ntSortDescsodiag J; 

NSSet *oldSeJ.ection = [self saveSelectionProiaTabieioTablfi]; 

// son the NSMutableArray 

[oData EortUeingFuncilon: ORDERJJ¥_CQNTEXT context:&cixi]; 
loTsble reloadData]; 

[self costoreS?lectIon:oldSelection toTable:uTableJ; 

J 


Drag and Drop to Rearrange Rows 

Some tables benefit from the ability to drag rows around to 
reorder the table's contents. For instance, the “International’* 
panel of the System Preferences allows you to specify the 
languages you prefer to use when using the Mac. 

According to the documental ion on the NSTableDataSource 
informal protocol, there are three methods you would 
implement in your table s data source to facilitate drag and 
drop. One is for grabbing the data when you drag; one 
validates whether data can be dropped on your table; one 
perfonns the drop, k sounds simple, but there are always 
subtleties to work through. 

If your table is going to handle drag and drop, you need 
to decide what operations that entail. In this segment, we are 
merely rearranging rows in the table, then it is simplest to 
merely keep track of the row index (or indexes) being 
dragged, so that your code can directly manipulate the data 
array's ordering. 

The first of the three methods, tableView: wnteRows: 
toPasteboard: is tasked with putting data corresponding to the 
given rows that are Ixring dragged into a pasteboard. In 
Cocoa, there are multiple pasteboards available, and each 
pasteboard can contain multiple kinds of data. In our case, we 
put a representation of which row indexes were dragged, for 
the purposes of mere row reordering. This is identified as a 
constant siring, *MyRowUstPasLelx)ardType\ identified in the 
code as kPrivateRowPBType. (If your program were to have 
multiple table views — where ii would be possible to drag 
from one table to the other — you’d have to take care to 


specify separate pasteboard data types, and/or encode the 
source of the row indexes, so you wouldn’t inadvertently mix 
apples and oranges.) 

To encode is the list of dragged row indexes, we just use 
the NSArchiver class to turn the NSAmiy we are handed 
containing all of the row indexes into a single NSData object. 

Listing 12: DraggableSource.nl 


tabic View; writcKow*: tofestebraftL 
[hit a list of i lie given rows onto a private pasteboard 

- C BOOL)tableView:fNSTableView *)inTableView 

writ©Rows: (NSArray*)inRows 

toFastehoard■(NSFaateboard*)inPasteboard 

t 

NSData *archivedRowData 

- [ N S Archiver fl r c hi ve dDat a W i t Moot Object: InRows J: 

[inFasi©board declareTypes: 

[NSArray arrayWithObjcct5:kFrivateRovPBType, nil] 
owner: nil 1 ; 

[inPasteboard setDala: archivedRowData 
forTyperkPrivaceRwPBType]; 
return YES: 

I 

The next method, tableView; validateDrop; proposedRow: 
proposedDropQperatton:, Ls needed to validate whether a drop 
can occur; this is called repeatedly as the user drags over the 
table view. Tables can accept drops onto a row, or between 
rows; in our case, we only want to accept drops between rows 
(the given NSTableViewDropOperation must be 
NSTableViewDropAbove), and we only want to accept die drop 
if the clipboard has our own private data type. 

listing 13: DraggablcSource.m 


ubivView: vaDtlatdlmp: proposedRow; prapvsedDropOperatitm: 
Determine whether a drop cm take place, anti how h wiJI t>e treated. 

(NS D r a gQ per a t i on) r.a b 1 e V i ew; (NSTa b 1 e Vi e w*) inTab leView 
validateDrop:{id OJSDragginglnf0>)inlofo 
proposedRow:(int)inRow 
proposedD ropOperation: 

(NSTab 1 e V i ewD ro pOpe rati on) i rtOpe r a t Ion 

( 

// U>ok ior our private type for reordering mws 

NSString ’type 

*= llinlnfo draggingPasteboard) 

avallahleTypeFromArray:[NSArray 

arrayWlthObjects:kFrivateRovFBTypR. nil]]; 

if (LnOpetation NSTableViewDropAhovc 

&& [type isEquaiToString:kPrivatoKowFBTypeJ) 

I 

return NSDragOperationHovc; 

I 

return NSDragOperationNone; 

J 


The final method, tableView: acceptDrop: row: dropOperatiort: 
actually performs die drop. This method checks the pasteboard 
type available, and if it is our private identifier representing row 
indexes, it performs the data rearrangement. It works by 
copying out the appropriate rows of data from our data array, 
replacing them with special NSNull values; dien it inserts these 
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data rows into ihe table; finally it compacts the table by 
removing the NSNull placeholders. 

Listing 14: DraggableSource.m 


lalikVkw: act-rpiDrup: row: dfopOpi ration: 
Handle j. drop. If its our private pasteboard listing the rows to move* * actually move 
the data 

(BOOL)tableView:(NSTftblfiVicw*)inTa'bleViev 
acceptDrqp: (id (NSPragginginfo)) ininfo 
row: (inr)inRow 

dropOperation:(NSTableViewDropOperation)inftpecation 

! 

// Lode for our private type for reordering rows. 

NSKtrlng, *type - [fjnlnfn draggingPasteboard] 
aval 1 .abloTypoFroruArray t [NSArray 

arrayWithQbjeL-isrkFrlvaieRovPRType, ni111: 

if ([type isEqualToString:kPrivateRowPBType]) 

( 

NSData *archivedRovData 

“ ffinlnfo draggingPaneboard] 
d a r a Fo rTy pe:k Privat eRowPBType]; 

NSArray * rows * [NSlinsrchlver 

unarchiveObjectWi thf)ata: a rcbi vedRowData]: 

NSMutableArray * movedRows 

- I NSMut able Array arrayWithCapacity: [rows count]]; 
NSEnumerator "theEnum “ [rows objectEumnerator]: 
id rheRovNimber: 

// First collect up all the selected rows, then put null where it was in the array 

while (nil l w (theRowNuinher ■ [theEnuiii nextQbject]) ) 
t 

im row = [LlieRowNumber intValue]: 

[piovedJtovS addObject: [obala objectAtIndex:row] ] : 

[oData replaceObjectAt1nd ex:row 
withObject: [NSNull null] j; 

I 

//Then insert these data rows into the army 

[oData roplacnCh jneTf!TnRange:NSMakeRange(inRow. 0) 
withObj ee taFromAr ray: tnovedRown]; 

// Now, remove the NSNull pUteholders 

[oData removeObjectldenticalTot[NSNull null]]; 

// And refresh the table (Ideally, Wt should turn off any column liigldighting) 

[inTableView deselectAll:nil]: 
tinTableVlew rcloadData]: 

I 

return YES: 

> 

One last step remains. The table view must register itself 
in being interested in the pasteboard type representing our 
row indexes; a good place to perform this is in your 
awakeFromNib method, 

[oTable regifile rForDraggedTypen: 

[NSArray arraybU thOhjectsikPrivateRowPBType.nil]]; 


Drag and Drop of Data 

It can also be useful to drag data from the tallies into other 
applications, or ini[X>rt data via drag and drop. In tills segment, 
well explore data export via drag and drop, leaving importing 
of data as another proverbial “exercise for the reader." 

For dragging data out, only Lhe first method, table View; 
wnteFtows: to Pasteboard:, is affected, as it packages up the data 
to export to another program. (If you were to allow dropping 
onto your table views from external sources, such as cells 


dropped in from a spreadsheet, you would want to modify 
tabieView: validateDrop: proposedRow: proposedDropOperation; 
and tableView: acceptDrop: row: dropOperation: to accept other 
types of pasteboard daia, and register for those pasteboard 
types in your awakeFromNib method.) 

Our TabieTester program adds two additional pastelxiard 
types to the pasteboard in addition to the private type for 
rearranging rows: NSStrtngPboardType (generic text) and 
NSTabularTextPboardType (tabular text, as for a spreadsheet). 

To build up the strings, we enumerate through each of the 
rows; for each row, we enumerate through all the columns. 
Each row of data fills up the buffer with strings for each cell, 
separated by a tab or a newline, with a final cxLru newline after 
each row. If your application needed the data formatted 
differently (for instance, always separated by tabs, or always in 
a specific column ordering regardless of the current display, or 
as rich text), you would modify this code to build the 
appropriately structured data. 


Listing 15^ DraggahIcSuurce.il] 


tableView; writcRows: toPastcboard: 

Write the text data on the given rows onto the pasteboard 

(BOOL)tableView:(NSTableViev 1 )inTabloVIev 
writeRows;(NSArray*)inkowa 
tqpasteboard: (NSFasteboa rd *) inFas t aboard 
I 

NSData *a rehivedRowbata 

™ [NSArchiver archivedDataWithRootObject:inRows]; 

NSArray ■ tableCohtitns ® [inTabloVlew tableColtiflma]: 

NSMutab1eString ‘tabsbuf ~ [NSHutahleString string]: 
NSHutsbleString ‘textbuf = [NSMutableString erring]: 

NSEnumerator *rowEnum * [rnRows objectEnumerator]: 

NS Number *rovNuffiber: 

while (nil 1= (rnvNumber ^ [rowEnum nextObjectj) ) 

I 

int row ~ [rowNutnber IntValue]: 

NSEnumerator ‘colEnura ■ [tablflCalunins objectEnuraerator]: 
NSTabieCqlumn *col; 

while (nil 1= (col = [colEnum nexiObject]) ) 

I 

Id eoluianValue 

* [self tableViewiinTableVlew 

obJectValueFarTabieColumntCQl row:row]; 

NSStrlng, * col umnSt ring " i**: 
if (nil != columnValue) 

I 

columnString " [columnValue description]; 
l 

EtabsBuf appendFo rma^: 8"%@\ i 11 , columnSi ring]; 
if (! [colunmString isEqualToString:^ 1 '"]} 

I 

[textBuf appendFarraat.columnstring]; 

I 

I 

// ddeie the last tab (But don't dtdetc the last CR) 

if (ItabsBuf length]) 

( 

[tabsBuf deleieCharactersInRange: 

NSHakeRange([tabsBuf length!-1. 1}]; 

I 

// Append newlines to both tabular and newline data 
[tabsBuf appendString:§"\n ,, l; 

[textBuf appendstring z^Vn"] : 

l 
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// Delete the final new lines from the text and tabs bnf 

if frtahsBuf length]) 

i 

[tabsBuf deleieClmi acterslnRange: 

NSHakeRanget(tabsBuf length]-1, 1)J s 

1 

if ([taxtEtif length]} 

I 

EtexiEuf deleteCharactersInRange; 

KSHakeRange(ftextBuf length}-], t)]: 

i 

// Set up the pasteboard 

(iriPasteboard declareTypes: 

[MSArray axrayWithObjects:NSTabularTextPboardType * 
NSStringFboardType. kPrivateRowFBType, nl11 
owner;nil]; 

// Put the data into the pasteboard for our various types 

[inPasteboard setStrlng:[NSString stringVithString:textBufI 
forType:NSStringPboardTypeJ; 

[inPasteboard setStrlng:iNSStrirtg stringWithStritigitabsBuf 1 

IorType;NSTabularTextPboardType]; 

UnFasteboard setData: arcMvedRowData forType; 
kPrivateRowPBType] : 

return YES; 

I 


One obscure trick remains* In order for you to he able 
to drag data outside of your application, you need to 
override a method in NS' Id hie View. Your table view must 
therefore be of a custom class. If you don’t override this 
method, you will not be able to drag data out of a table into 
another application! Hopefully Apple will fix this in a future 
version of Mac OS X. 


Lisling 16: Typea bead'Tab leV lew. m 


drj£ging,Vmivc< )peni lion MiiskftirLt K/aJ: 

Allow drags outside of an application 

(NSDragDperation)draggingSoui:c«DperationMaskFcirLoca]: 
(BOOL)isLocal 

t 

if (isLocal) return NSDragOpetationRvery: 
else return NSDragOperarionCopy: 


Copying Rows to the Cupboard 

Willi drag and drop supported, it's actually quite easy to 
add the capability to copy selected rows of a table to the 
clipboard. We employ the method tabteView: writeRows: 
toPasteboard:, passing in ihe general pasteboard, to respond to 
the Copy menu item. We check to make sure that the table's 
data source implements that method, so this method will fail 
gracefully if the current table doesn't support the clipboard. 


Listing 17: AppController.ni 


//eurrmf table view by gening the lab view item s imUall ins lR esponder, 

//wbk’h b set in the nib 

id currentTable 

= UoTabViev selectedTabViewTtsn] initislFirstKesponder] : 

// Now put Lht selected rows in the genera] pasteboard 

if (f (curretitTablo dsmSource] respondSfoSelec tor: 

^selector (tableViev: wrUeRows: toPasteboard;) ]) 

( 

(void) [[currentTable dataSourceJ tableViev:currentTable 
writeRows:[currentTable selectedRows] 
toPasteboard; fNSPasteboard ganeralPasteboard]1; 

) 

1 

It’s actually that simple! All that is missing is a method 
in NSTa hie View called selected Rows, to return an array of row 
indexes. This is fixed quickly by adding a category method 
to NSTableView. 

Listing 18: NSTableView+utlLm 


select edRtws 

Rdum an array of the selected row numbers of the table 

- (NSArray *) select ndRows 

I 

NSEriiimera lot ‘theEnum s [self selectedRouEnumerator]; 

NSN nmbe r * towNtimb e r ; 

NSMutableArray t rowHumberArray = [KSKtitahleArray 
arrayVithCapaciry:[self numberOfSelectedRown]]; 

while (nil t* (rowNurobci ^ [theEnua nexiQbject]) ) 

f 

[ rowNuiuberArray addObject; rowNumber I ; 

1 

return rowNumberArray: 


Until We Meet Again 

If you've made to the end of part two, congratulations — 
you can go Forth and create some amazingly rich table 
interfaces* But there are still more cixjI things you can do with 
NSTa hie View, and this is why there's another part in the series 
on the way. Tune in next month for part three, in which well 
some advanced techniques, including the technique for correctly 
displaying those trendy striped tables that you see in the 
“iApps, 4 * anti a subclass that merges certain cells together into 
wider cells. 


copy: 

Handle ihc request to copy rows from the table. 

(IBAction) copy:(id)sender 

[ 

// Get ihe NSTabkVtew we want to copy from, in this case, we determine the 
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Place the display up to 15 feet away from 
the CPU without any loss of quality. 

Extend the cable on your 
15", 17", 22" or 23" Apple 
display by 3 meters (10 ft). 







Cry wolf 

COMPUTERS 




■ ‘i filCS 

Keyboard 


This silicone-cast keyboard is completely tollable 
and liquid resistant, making it perfect for travel or 
harsh conditions. 


The CoolMacKeyboard is the world's most flexible keyboard, 
in more ways than one. 



Dr. Bott's complete focus is serving resellers with hundreds of products from over 30 manufacturers. We 
scour the globe to bring you the best Mac products. New resellers and manufacturers are always welcome, 

503.582.9944 www.drbott.com 877.611.2688 (Toll Free) 


























REVIEW 


By Michael R. Harvey 


Star Wars: Galactic Battlegrounds 


Ed, Note - This is only going to hurt for a second, then a 
little pressure y then it's going to hurt really bad f so just try to 
breathe , You might smell a burning smelly just ignore that 


What’s this? A game review in MacTech? Isn't that one of 
the signs of the Apocalypse? Actually, no. Doing an entire 
games issue would be, and we aren’t there, ar least not yet. 

No, this is more of an intervention than the end of the 
world (although ii might fed like it at first). Have you looked 
in a mirror lately? You're pale, your posture has gone to hell, 
and the IV of Dr. Pepper isn’t helping your complexion out. 
It's high time you stopped coding for a bit, and do something 
else with all the processing power at your fingers. Something 
frivolous. Notice we aren’t recommending you actually turn 
the computer off, and go outside for some sun and fresh air. 
We can't expect miracles right out of the gate. Well start with 
baby steps. You can still have the bad posture, and the 
Mountain Dew injections, but let's try some completely 
wasted fun time. Let’s play a game. And why not play one 
ported by those geniuses at Westlake Interactive and 
published by the folks at Aspyr, the company that has 
published some of the best titles the Mac platform has seen 
the past several years. 

Star Wars: Galactic battlegrounds is a recent release 
from Aspyr. As you might have guessed by now, it is a game 
from the Lucas Arts guys centering around everyone’s favorite 
space opera, Star Wars. This game is from the real time 
strategy category, similar to Command and Conquer nr 
SuirCralt. Built on the Age of Empires 2 engine, you are able 
to take command of one of six different factions, from the evil 
Galactic Empire, to the Naboo, to Wookiees. You are then 
tasked with missions, and complete them through managing 
your resources, trading with your allies, building your forces 
and defeating the enemy. Good times! 

The system requirements for the game are actually quite 
tame, A G3 processor, 64 MB RAM, a video card capable of 
displaying 256 colors. Not too taxing for almost anyone, is it? 
Network play can be done over a LAN, or even wit Si a 28.8 
modem (although more is always better when it comes to 
gaming, as it is with most things). The graphics look great. 
Units, and structures are rendered with good detail. It is easy 
to discern who is who. The sound is quite nice, as well. You 
can see, and hear, the effort that went into the details to make 
the Star Wars universe come alive on your screen. 


if you are already familiar wlrh Age of Empires 2, this 
article is not for you, go outside already. If you're still with 
me. and have played Age of Empires 2, you are pretty much 
ready to go. Galactic Battlegrounds uses many of the same 
interface controls and command keys. As with Age, having a 
multi-button mouse really helps out. That right button gets a 
work out in this game. Control clicking so often gets to be a 
drag, and we just can't have that. 



If you are unfamiliar with this type of gaming, you might 
want to start out with ihtr Basie Training missions. In these, 
you will be led by Qui-Gon Jinn in how to establish your base, 
gather resources, build units and structures, and conduct 
battle. It’s not absolutely necessary, though. The controls 
really are quite simple, so you can jump right into the game if 
you wish. 

Game play revolves around either single player or multi¬ 
player use. 

In single player mode, there are a few options for game 
play. You can choose to play the Campaigns. These are a 
series of missions you are tasked to complete. You become 
one of several characters from the Star Wars universe. The 
campaigns take you through much of the mythos of Star Wars, 
not only ihe movies but the novels, as well. 

You also have the option of playing stand alone missions. 
In these games, you set the parameters, such as number of 
opponents, type of map. and starting resources. The game then 
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puts you on a map, and you fight it out based on Lhc rules you 
established. Included as part of the game is a scenario editor 
in which you can create your own imps, and play conditions. 
These can he shared with other gamers, as well as you being 
able to play scenarios created by other users. 

There are two ways to engage multiplayer action. One is 
where the host sets up the games rules, and other gamers join 
in. The others access the hosts game either over a LAN, or 
over the internet. All connections are via TCP/IP. It the 
gamers are on the hosts LAN, they will see the game 
automatically. Users coming in over the Internet will need to 
know the IP address of the host to join the game. 

The other method of play in Galactic Battlegrounds is via 
Game Hanger Game Ranger is a freeware application that 
helps you link up with other Mac players, and set up online 
games. Recently, Scott Kevil, Game Rangers author, released 
a public beta of version 3.0 which adds support for OS X. If 
you do not warn to toad up beta software, you will need to 
boot into OS 9 to play online via the current version of Game 
Ranger. However you access it, Game Ranger is a very 
worthwhile tool to have for gaming. It currently supports over 
50 game titles, and is Mac only. 

This game is a great ride, and wretchedly addictive. The 
many detailed options you can change and tweak will allow 
you a vast array of game possibilities. You will definitely 
waste a goodly amount of time on this title. Plan accordingly. 
The only drawback you may run into is with the difficulty 
settings. Easy is too easy. There isn't much challenge. The 
enemy just waits for you to come mop the floor with them, 
jumping from there to normal could be a shock, as the 
normal selling will smack you around handily if you're not 
ready for it. Hard is, of course, hard, but it keeps your pulse 
rate up. 

It is unfortunate that so many of the games created 
around the Star Wars universe don't make it to the Macintosh 
platform. It is always a treat when companies like Westlake 
and Aspyr secure the rights to one of the many great titles 
LueasAits produces. Galactic Battlegrounds is no exception. 
Hopefully we will get to see more of these games in the near 
future. And in fact, we will very soon. Star Wars jedi Knight 
11: Jedi Outcast is currently in development for release later 
this year, Galactic Battlegrounds has an MHRP of $50, and is 
available from almost anywhere Mac software is sold. 

One last note. Kudos to Aspyr for their packaging of 
Galactic Battlegrounds. The box is small, and compact; just 
big enough to hold the CD. manual, and technology chart. 
Not one of these 47 pound monstrosities that hold one Cl). 
They saved a tree or two. Good for them. 

http://www.aspyr.com/ 

http://www.gameranger.com/ 
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IPIletmonitorX 


• The Swiss Army Knife of mac OS X 
Internet Diagnostic Toots 


• IS fully Integrated Tools- 
monitor. Link Rate, Address Scan, 

TCP Dump and more 

• Troubleshoot and Solve network Problems 

• Responsive, Intuitive, Easy to Use Interface 

• fast multi-Threaded Architecture- 
see network behavior as it happens 

• 21-Day fully functional free Trial 



Download Your Copy now at 

www.sustworks.com/mac 
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To meet deadlines, developers have 

^ ^ PC' rf cd rc^ 

2. Cut Corners 


ejaft.rrfar^lf s-M 


With rival SCM systems, the only way to quicken 
the pace is to cut comers - but in the long run 
you pay the price with missed deadlines, 
uncertain contents, buggy releases and no way 
back to previous builds. 

With Perforce, the fast way is always the 
right way. Install it fast, learn it fast, execute 
operations fast. With other SCM systems, 
developers face an unpleasant choice: 
do it The right way or do it the fast way. 

Perforce's speed and reliability mean fast Is right. 
See how Perforce compares with other 
leading SCM systems at 
http://www, pe rlorce. co m/perforco/re vi e ws, him I 


Run at full speed even with hundreds of users 
and millions of file s. At the core of Perforce lies 
a relational database with well-keyed tables, 
so simple operations can be accomplished in 
near-zero time. Larger operations (like labeling 
a release and branching) are translated into 
keyed data access, giving Perforce the scalability 
that big projects require. 

Work anywhere. Perforce is efficient over bigh- 
tatency networks such as WANs, the Internet and 
even low-speed dial-up connections. Requiring 
onlyTCP/IR Perforce makes use of a well-tuned 
streaming message protocol for synchronizing 
client workspace with server repository contents. 


Develop and maintain multiple codelines. 
Perforce Inter-File Branching M lets you merge 
new features and apply fixes between codefines. 
Smart metadata keeps track of your evolving 
projects even while they develop in parallel. 

Truly cross platform. Perforce runs on more than 
50 operating systems, including Windows and 
nearly every UNIX' variation, from Linux and 
Mac OS X to AS/400 and more. 

Integrate with leading IDEs and defect trackers: 

Visual Studio.NET , Visual C++ , Visual Sasic*, 
JBuilder , Co do Warrior, TeamTrack', Bugzilla*, 
Control Center, DevTrack packages, and more. 


Perforce 

SOFTWARE 

Fast Software Configuration Management www.perforce.com 


mmm. 


Download your free 2-user, non-expiring, full-featured copy now from www.perforce.com 
Free (and friendly) technical support is on hand to answer any and all evaluation questions. 
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We're Easier. 

Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic creates native compiled applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments. It's the po werful, easy-to-use tool for creating your own 
software. Each version of your software looks and works just as it should tn each environment. 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 
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NEW VERSION 


Come see us at Macworld in MacTech Central! Download a free demo, www.realbasic.com 



















